I've designed the application, figured out how the components will link together, and have sat down to start coding. But before that happens, I'm starting to think rather seriously about documentation for this application (due simply to it's size).
This leads to the question: How do you document your application?
When do you start?
Do you write the documentation before the application is actually coded, and base all of your code on that "vision"?
Do you quickly write down the design, and then document while coding (JavaDoc style)?
Do you just write the entire program and tackle problems as you go, and then write documentation afterwards (to avoid updating documentation mid-way through)?
What style do you use?
Do you document every class and their methods individually?
Do you divide your documentation into "packages"?
Do you document procedural pages?
Do you document individual functions and processes?
What level of detail do you provide?
Do you write brief, point form descriptions of what the section does?
Do you write several lines of documentation for important elements?
Do you write pages of documentation for specific sections?
Do you provide tutorials for the application in general?
Do you use a combination of these for different levels of importance? What is your comment-to-code ratio?
What format does your documentation take?
Do you distribute your documentation as an individual web application? If so, do you use dynamic or static pages, XML or HTML?
Do you encode your documentation in CHM or other file formats?
Who does your documentation target?
Do you target developers specifically and include low-level details?
Do you target end-users and focus mainly on the implementation?
Do you write multiple versions of your documentation for different audiences?
Does your choice depend on the type of application you write?
I'm curious to know what procedures other developers take when it comes to documentation.
As I write my code, I document using comments (making sure to always include pre- and post-conditions for all functions, etc); I've lately started trying to follow the PHPDoc style, but haven't been sticking to that very well. This documentation is aimed at myself or another PHP developer who needs to read and/or modify my code and its sole purpose is to make the code understandable.
Only when I'm done with coding and ready to go live do I create any end-user documentation. The reason here is that 10 times out of 10 the final product is significantly different from the initial plan, and thus any documentation based on the initial plan would be worthless. My documentation at this stage is targeted at users of my application, i.e. my target audience is the same as the target audience of the application itself. For example, I recently built a small code repository intended to provide an easy interface to finding and reusing pre-written PHP code to aid myself and the other PHP developers I work with; the documentation for it is written with this audience in mind. Another recent project was a CMS to allow management to easily post content to the website; the documentation, then, is aimed at these mid-level managers.
The level of detail is whatever it needs to be to let the target end-user audience use my application successfully. For fellow developers, my documentation is a little less detailed in the "how to use" side of things and a little more detailed in the "what's going on behind the scenes" side; for the less tech-savvy, I leave out any detail about the backend and focus on as much detail as I can reasonably write about the frontend. If I get calls from people asking how to do things, then I add more detail; rarely do I ever take away detail. Really, the more detail you can include (without confusing your audience), the better.
The end-user documentation I write is usually several static XHTML pages, a la MySQL or PHP, although the CMS is (ironically) documented in the CMS itself, i.e. each page of the CMS's documentation is a page in the CMS itself, albeit in a completely separate tree than the main CMS site.
Last edited by kromey; Jul 5, 2007 at 11:41.