Generating documentation
I have seen many projects with a lot of documentation and also projects with almost no documentation and almost none that have the right amount of documentation.
Some methodologies require writing a lot of docs (planning, design etc ...) before starting to write some code, those docs became the pillars and the foundation of the projects, but in real life change happen. Therefore all the docs become outdated pretty fast so anyone looking for something useful in that documentation becomes impossible. People come to the project and they waste a lot of time reading documents that are inaccurate, they will have a wrong idea about something, will "break" it and then time will be spent to fix it, the person will be notified that he made something wrong, he will tell that he read it in some document, then it will be told that some documents are not updated so since discerning between what's right and what's wrong in the docs is so complicated they finally give up with the docs (after wasting lots of time).
Some other projects that are poorly documented, mostly because the managers have faced the "lots of docs" situation (or they lack any kind of methodology) and they say that documentation is not important and that anyways it becomes out dated. People come to the project and since there are no documents they will start working with no standards, making errors and making other people loose time fixing them and explaining them that even though there are no docs there are many unwritten laws that must be followed.
I am not a document lover, in fact, I hate documenting. But it is necessary, so, the question is: which is the correct approach? My personal view is a balanced course. Not too much and not few.
Write documentation when you plan any project, otherwise you won't be able to share ideas with the customer or to have any formal agreement about what is going to be built. Write documentation when designing, therefore you will have a plan how to build it. This manually generated documentation should be as brief as possible. I have seen documents of 200 pages that transmit an idea that could be communicated in 10 pages. (If you want to be the next Tolkien or Cervantes you are in the wrong profession, or at least do it in your spare time). I see this documentation as "historic" that means it shouldn't be updated, put a date on it and mark it as read-only.
Then think of what kind of documentation is going to be "alive" (that needs to be updated) that is going to be useful and that it will save more time than it will take updating the docs. This could be, for example, the API of the common components, user manuals and coding standards/best practices. Include in your estimations the task that it takes to update the documentation, otherwise this approach will fail since people will forget to do it or they won't have time to do it.
Some guy should have a role that will be the document manager (normally the guy in charge of standards and methodology)
Don't store that documentation in a "hidden" place. Make it visible. Centralize it; don't scatter the docs between many places, that way finding it will be hard enough for developers to forget updating the docs. A good place to store it is SharePoint, it centralize the documentation, it can manage access rights so only the right people can modify it and the rest can view it, it notifies the team when a document has been updated, and it is easy to update and collaborate among team members. not all has to be in a word document, SharePoint can manage WIKIs (which can be a good tool to document the most common errors ) and forums (which may be a good tool to discuss how to solve a tricky problem, therefore leaving a written evidence on how a conclusion was reached)
Once you have the documentation, don't stop at that point and try to automate as much as you can. If you have a standards documentation try using tools like FxCop to enforce it by writing your own rules (Visual Studio 2005 has that tool built in). Developers will read docs but they may forget it. FxCop will remind them.
For API documentation, use automatic document generation tools like SandCastle. The documentation will be comments in your source code and a chm help file will be automatically generated from the source code.
I will expand more on these two useful tools in next posts.
Comments
Anonymous
June 16, 2009
PingBack from http://topalternativedating.info/story.php?id=11081Anonymous
November 13, 2010
f you are looking for a reporting and/or document generation system on .NET, take a look at this review of Windward Reports - it gives a good picture of its capabilites it can be used to generate reports that can be used to create template in excel, powerpoint or ms word There is a really interesting reporting/docgen system where you design the templates in Microsoft Office. Makes the layout trivial. There's a good review of it at An Evaluation of Windward Reports. u can try it by clicking it below. and i am very sure that you would like this tool. www.dotnetreports.info/windward_review.htm