Build documentation to last - choose the agile way

Lately I wondered what the best way to document a project is?

My documentation experience vary among different tools and methodologies.
I would like to share some observation I have and a conclusion about the best way to document a project.


The documentation could be classified to the following categories:

Documentation place:

• In line code/ version control system (via code commit description)
• In separate server linked to the code
• In separate server, decoupled from the code (no direct linkage)

Documentation done by:

• Developer
• Product team/ Design team / architects
• Technical writers

Documentation too:

• IDE
• Design documents
• Modeling tool, Process Flow
• Wiki
• version control (e.g. git, svn,..) commits
• Interface documentation

Not surprisingly there is a direct correlation between the tool used , the person who document the code, the amount of documentation, the "distance" of documentation from the code and the accuracy of that documentation.

Given the categories above it could be organized in the following manner:

• Developers
• In line code/ version control system (via code commit description) 
• IDE/ version control

• Product team/ Design team / architects
• In separate server linked to the code 
•  Design documents, Interface documentation

• Technical writers
•  In separate server, decoupled from the code (no direct linkage)
• Modeling tool, Process Flo, wiki

Developers tend to write short inline documentation using IDE, well interface semantics and complementary  well written code commits.
As long as the person who document the functionality has more distance from the code, the documentation would usually be in places more decoupled from where the code exist and more comprehensive.

From my experience, even good design tend to change a bit and even if the documentation is good but is decoupled from the code, most chances are that it won't catch up with code change.

In real life, when requirements keep coming from the business into development, it sometimes brings with it not only additional code to directly support functionality, but often we see the need for some structural or infra change and refactoring.

The inline code documentation is agile and change with minimum effort along the change in functionality. If the developer submit the code grouped by functionality and provide good explanation about changes that were done it would the most updated and accurate  documentation .

I know that some of you might wonder about heavy duty design or complex functionality documentation.
I would recommend tackle these issues as much as possible inline the code, for example, assuming you read some pattern or some bug solution in the web put a link to that solution near the method/class which implement the solution. Try to model your code by known patterns so it would avoid documentation. Try to use conventions so it would reduce amount of configuration and make your code flow more predictable and discoverable.

This approach is even more important when managing a project in agile methodology.
Usually such methodology would rather direct communication with product/business to understand requirements rather than documented PRDs. This makes it even more important to have the code self explanatory easy for orientation. Moreover, frequent changes in design and business change would cause decoupled documentation soon be obsolete (or will drag hard maintenance)

Although it sounds easier said than done and it is not a silver bullet for every project, writing documentation as close as possible to the code itself should be taken as a guideline / philosophy when developing a project.


Acknowledgment - above image was taken from lwiki's Gallery : https://picasaweb.google.com/lh/photo/ScQcKRBjhY7UvnzJ7vNArdMTjNZETYmyPJy0liipFm0