> How do you guys go about technical documentation, how do you write docs that > tell other people (not necessarily technical, but project participants) how > your code works, what the rules are, what the re-use potential is, how the > UI works etc. > > What tools do you use for the job? Word? Visio? Wiki? How do you tackle it > and when? Before writing your code? After?
For us, the exact set of documentation deliverables is very project-dependent and is thrashed out at a high level at project initiation time and then in more details at the beginning of each project stage. It depends on the complexity of the job, the customer's expectations and the development method used for the project, but in general you need to have documentation tasks in all three places - beginning, middle and end. You need to document the functional and "non-functional" (performance etc) requirements up front or the project will fail. You need to document what you're doing at each stage in order to have a managed process (imo this is true even if you're doing "agile" development). And you need to document what you've done at the end, or the documentation will not reflect reality. We do still use Word/PDF for those documents where a simple, visible version control scheme is critical. We store everything in our web-based project support environment as a central reference point. Being basically a CMS, besides storing files it allows you to create more free-form web-based documentation as you go along, whether as traditional pages or blog/wiki/forum/helpfile entries. It also creates interactive diagrams. We use a lot of diagrams because they are information-rich and (some) customers can understand (some of) them. We use all sorts of diagramming techniques, both from UML and older toolsets. The only thing I would caution against is creating too many detailed how-to documents with embedded screenshots - they become a real pain when you want to change things. An up-to-date Captivate demo is much more likely to be correct and consistent. However, sometimes customers want things on paper. Nick ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| Message: http://www.houseoffusion.com/lists.cfm/link=i:4:242893 Archives: http://www.houseoffusion.com/cf_lists/threads.cfm/4 Subscription: http://www.houseoffusion.com/lists.cfm/link=s:4 Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=89.70.4 Donations & Support: http://www.houseoffusion.com/tiny.cfm/54
