Home » Agile » Build documentation to last – choose the agile way

About Gal Levinsky

Gal Levinsky
Graduated B.s.c Information System Engineering on BGU University (2004). Been working on large cloud based ERP application in SAP for 7 years and as a development group manager in affiliation company. Co-founded few startups in the domain of social web.

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.
(0 rating, 0 votes)
You need to be a registered member to rate this.
Start the discussion Views Tweet it!
Do you want to know how to develop your skillset to become a Java Rockstar?
Subscribe to our newsletter to start Rocking right now!
To get you started we give you our best selling eBooks for FREE!
1. JPA Mini Book
2. JVM Troubleshooting Guide
3. JUnit Tutorial for Unit Testing
4. Java Annotations Tutorial
5. Java Interview Questions
6. Spring Interview Questions
7. Android UI Design
and many more ....
I agree to the Terms and Privacy Policy

Leave a Reply


This site uses Akismet to reduce spam. Learn how your comment data is processed.

Notify of