I'm a Software Developer with over a decade's worth of experience in the IT Industry. While primarily a Java Developer I've working in - among other things - everything from C to Visual Basic to JavaScript to Ruby to Objective-C to C#. I officially consider myself a member of the cult of Lisp which tends to colour the way I think about how code should be written Julian is a DZone MVB and is not an employee of DZone and has posted 11 posts at DZone. View Full User Profile

Documentation that is useful

02.06.2012
| 3925 views |
  • submit to reddit
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?

 

From http://dotneverland.blogspot.com/2012/01/documentation-that-is-useful.html

Published at DZone with permission of Julian Exenberger, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Martin Chalupa replied on Mon, 2012/02/06 - 1:15am

Nice article I totaly agree. I have one question. Where do you have documentation that it is easily searchable, easily accessible and easy to update ... ? I'm satisfied with wiki but maybe you have another experience.

dieter von holten replied on Mon, 2012/02/06 - 4:15am

you claim to be a developer of information systems for commercial entities.

ask the maintainers of your code - ask those who maintain code you have written 3 years ago...

Fabien Bergeret replied on Mon, 2012/02/06 - 4:59am

My solution: on-board developers on a maintenance project: they'll soon realise all the information they miss. After that, they'll document very accurately, just in case they work on the maintenance...

Julian Exenberger replied on Tue, 2012/02/07 - 8:09am

I speak as both a person who has handed over code and had their own code maintained.

And from that point of view I find contextual information to be the most important.

If you can checkout, build, deploy, configure and execute a piece of software, from instructions I am already half way to understanding how it fits together.

Comments are nice, but the above is way more important to me.

 

 

 

 

Vinay Sambyal replied on Tue, 2012/02/07 - 4:57pm

Nice one, Julian. I have maintained and worked on greenfields and agree to your points. And, have same question as asked by Martin.

Norbert Rakosi replied on Wed, 2012/02/08 - 4:17am

Nice article. Indeed this is a really tough topic since by default developers hate writing documentation.
At our company, we have been trying out a new approach on making developers to create documentation, by removing all the clutter (like using a Word processors, formatting document, and such) and focusing on the content, since a good documentation is not about format, than it is about the information content...
We have set up a small Documentation portal inside the company, based on Drupal, in which we allowed developers (and not only) to share their information (documentations, ideas, problems) in simple form: using Blog posts, Forum topics and maybe Polls, all having the comment feature active to make contributing even easier.
It does fit the : searchable, easily updatable, always available criteria.
Drupal has a lots of nice modules you can make use of...
We are still in the early stages of introducing this but for the time being we did receive quite a lot of positive feedback from the employees.
We'll see... ;)

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.