Software Developing: Documentation

Software Developing: Documentation

Finally after two months without writing anything related with software developing here I am once again, this time to write about documentation. I've chosen this topic because besides being interesting we are currently deploying new documentation techniques at work.

Like I once read: Software developer documentation is like weather: everybody talks about it, but nobody does anything about it. Even if it sounds funny it is actually true, this happens - probably - for two main reasons:

1. The developers don't like to write documentation, it takes time, it's hard to write good documentation and once done it involves maintenance.
2. The managers sometimes see that the effort of writing documentation a waste of time (at least when it's not user oriented).

Seeing those two reasons just reminds me why most of the time software tests aren't developed.

Although there are always teams who document their work, and when talking about software documentation we can actually be talking about three distinct types:

1. Architectural Documentation

This kind of document shows the major picture of the application.
The idea is to identify sub-systems within the application and document the design of each one. Such design should be well explained showing all the needed requirements, the implementation details should be left out although, a few guidelines on what should be done in an implementation level may be present sometimes.

This documentation is most of the time written by the software architect and then presented to the developer team in order for the team to lay out a way of implement such requirements.

Such documents can contain UML explaining why each entity represented needs to exist and how they are related.

2. Technical Documentation

This kind of documentation is probably the one everyone is most used to write and talk about. Most of the time it's present on the source code explaining what a certain piece of code does.

There are automatic tools that help developers writing this kind of code like javadoc or doxygen - among others - the problem with this is that sometimes people start documenting the obvious… How many times haven't been writing the following code:

In my opinion such things are just a waste of time. Such situation - among others - just show another problem in software documentation, the quality of documentation. Even if sometimes it's rather easy to find documentation for a given application, it's rather difficult to find good documentation about it. But, what is good documentation?

3. User Documentation

Like the name indicates this is user oriented documentation in order users can successfully use the application.
This kind of documentation - most of the time written in a use-case basis - isn't always written by the developers, sometimes a new team tests the application and writes the documentation. This is done to avoid having developers that already know the system writing documentation for users - who know nothing about the system.

Most of the time this kind of documentation is presented to the user in form of user manual or tutorials.

These are the main types of documentation that can be present in an application's context, but most of the applications do not have the three, sometimes they don't even have one… I've been lucky because I've came across all the three at work.

Like I said before we are currently our architecture at FenixEdu. Since it's an application developed using Domain Driven Design our main effort is to be documenting the application domain.

The main idea is to achieve a white paper about our application's architecture, that can help other developers that aren't in the core team.
In other words we are documenting our architecture on a class basis. To do this we are using a wiki (MoinMoin) with a plugin developed by some guys from FEUP that allows us to render navigable UML directly from our domain modelling file. An example can be seen here. It's an interesting way of documenting - not to mention fast - and since the UML and source code is shown from a SVN checkout when the source code changes the documentation is automatically updated. Unless, of course, the logic of the object changes.

It's not a perfect solution - there is no such thing - but it's definitely a good way of documenting. Maybe documenting on a class basis is over documenting and we should focus on each sub-system that we have - after all that's how we explain things between each other - but that's something that time will say.

Until now there had been other documentation efforts but they all died - showing our hard is to actually produce good documentation for such a big project - but this time it seems things will be different.

I can't really say what's the best way to write documentation or how does actually good documentation looks like, but I can say that being able to navigate through the domain in an easy way helps me a lot on my daily development - well maybe not daily but it gets handy every time I'm starting to look to a part of the domain I'm new to.

Interested in Software documentation? My advice is to take a few minutes and read Software Documentation by Ian Sommerville.