About 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.
Related Whitepaper:

Applying Agile Principles To The Development of Smarter Products

Agile development has become a cornerstone of most software development organizations.

Marked by iterative processes that deliver incremental value over time, agile development has enabled organizations to manage software complexity more effectively and to improve quality and time to market compared with previous development processes.

Get it Now!  

Leave a Reply


7 − three =



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

15,153 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books