« 2.6.7, part III | Main | 2.6.7, part IV »
July 16, 2004
Examples: doc or code?
Netscape used to consider sample code part of the documentation:
Whether describing how to create hierarchies of objects in JavaScript or offering sample code to copy and paste, DevEdge Online documentation includes a variety of references to guide and assist development using Netscape products and technologies.
When reading with a developer or sys admin hat on, I certainly see sample code as belonging to the documentation. Why ask the question, then?
- We deliver sample code with the bits, not with the docs.
In other words, you may be able to copy code directly from the HTML version of the docs, but it's rarely as easy as it ought to be. - Sample code sometimes looks like somebody wrote and formatted it as the last little task to complete before sending a status report and leaving for a long weekend.
- Documentation and examples get out of sync.
That's like your right hand getting out of sync with your left. - Most "documentation" tools and formats force you to do some processing in order to include source code even from common languages verbatim
Yet another ease of use problem. What's a good fix?
Posted by Mark at July 16, 2004 10:04 AM