Saturday, January 14, 2012

Documentation that is useful

I was reading this article by Neil Mcallister on his Fatal Exception blog entitled "How to get developers to document their code".

Now it begs the question: What documentation is actually useful?

Well, like all things in general I don't think it's a simple answer, best I could say is; what works well in your context.

In my personal context as a developer of information systems for commercial entities I personally find  the following useful when it comes to documentation:
  • A decent setup and getting started guide: where to get the code, what tools and frameworks I need, how to build and configure it, and how to get it up and running.
  • Environmental information regarding the various environments: How the development, testing, QA and production environments are accessed, configured and managed.
  • A High level guide to how the components of the software fit together, with a one liner about what each component does.
  • An High level ERD or any other high level domain model is also quite useful.
Most of this documentation is really there to give context about the code, the rest I can figure out from the code itself.

I also have a list of documentation that I think is a waste of time and effort:
  • The above compiled into a document and then sent to die in something like Sharepoint: Useful documentation is easily searchable, easily accessible and easy to update referencing the actual models being used by architects and developers.
  • Low level code documentation: It always out of date and rarely ever reflects the truth of the implementation to begin with (It's also annoying to read, Sequence diagrams come to mind). The only time documentation like this is useful is when the documentation effectively becomes the code (using MDA for example).
  • Documentation done for the sake of process: No one will ever read this documentation except for the person who has to check that process is being followed. This seems to happen a lot in Waterfall environments where the process becomes so slow that organizations end up short circuiting pieces of the process in order to speed up development times.
What do you consider useful in your context?


Sandeep said...

As per my experience, not all document is useful special if too big to be maintained

Java Tutorial

Grofft said...

nothing that makes me want to pack up my toys and go home more than

- auto-generated documentation
- obvious documentation
- @author tags that include the date, time and second the file was generated. By the time I read your @author tag, it's likely that this is the only line in the class that you committed.

If you feel compelled to write a novel after typing a line of code, do it in the commit message.