[hand with pencil]
Stuff For Sale
2004 Summer Tour
About
Blog
Class Stuff
Email Me
Events
Gallery
Home
In The Press
Newsletter
Services
Smalltalk
Veggie Van Gogh

Credits
© 2002,
Bytesmiths

[this is simply a banner and menu bar]

Please patronize sponsors of this page!

Bytesmiths no longer is involved in software consulting. Maintenance of this web site is currently subsidised by unrelated business activities. Please pass the word to other interested folks, so I can continue to host this page!
Your site could be listed here, for as little as $12 per month! Go to Bytesmiths Press for details.

This site has been selected by PC Webopaedia as one of the best on this topic!
This site has been awarded a Links2Go Key Resource Award in the Smalltalk category!

[ prev | top | next ]

Documentation Needs

(This is a slide show. You really won't get 
anything out of it unless you have a graphical web browser with graphics turned 
on.)

- Link expression of design with implementation of design -- documents live with the code they describe, and the document is the specification for the code. This "Knuthian" concept is key to any successful design doc strategy; anything less, and "doc synch" is a big problem.

- Must be simple to use, if you expect it to be used with any rigor. The less integrated it is, the harder it is to use, and the more likely your project will slip back into "code it, then design it, then document it" habits.

- Enforcement may be appropriate when you have developers who are used to documenting their work after implementation (or not at all!). Automatic release controls may be imposed according to presence or absence of required project documentation. Must be supported by tools, such as comment counters and format compliance checkers, to avoid surprises at integration time.

- Seamless integration with code privacy -- users must only be able to change documentation for the code they are able to change. Documentation viewing permission must be controlled separately from the code it documents. This is necessary to preserve encapsulation during re-use.

[ prev | top | next ]