In the past couple of years I’ve written quite a lot of documentation, be it functional, technical, help files for end-users, flyers, proposals and much more. Most developers I know try to avoid writing these kind of things as much as they can, but let’s face it, it is part of our job.

At the moment I’m working in a team with pretty smart and experienced developers, but as it goes, one of our team members has been placed on an other team at a different customer and I was asked to replace him. The leaving developer had created an awesome framework, the code looks good, unit test coverage was (and still is) near 100% and it’s quite understandable if you step through the code. The only thing missing was technical and functional documentation. He and I tried to write some of documentation on the framework, but what do you need write in such documents?

Then it struck me, we developers are always trying to improve our coding and design skills and trying out new things and new languages, but we hardly try to improve ourselves in writing documentation. I’ve never had a class at school on how to write functional or technical documents. Also, I’ve never seen any specifications at a company on how such documents should look like or what you should describe. Most of the time you have to figure it out yourself, think of some stuff you would like to see in it yourself and create some UML-diagrams to keep managers happy (a lot of developers don’t understand UML, so they skip it). Another thing is where do you save these documents. Do you want them in a project repository (TFS), on a file share, in a CMS, etc.? In the past, most documents I’ve written were saved on some file share with a version number in the filename. A bit old-fashioned, but it works (for 1 editor at a time). At the current customer we’ve created a Wiki site in SharePoint in which we describe all the functional and technical specs. This is a bit better as to saving a Word document on a file share as everyone can change the contents and it’s available through the web. Also, it’s easier to maintain and SharePoint has it’s own versioning system for checking the changes.

I’d recommend doing writing Wiki’s (or some other CMS solution) over writing Word documents as it’s easier to maintain and more user friendly (in my opinion). This still leaves the question on what you need to write in the documentation.

It’s not very useful to describe in detail on what the code fragments do. The code will probably be refactored and updating the documentation will be forgotten. Also, if the code is clear enough, the developer can see for himself what a specific code block does. Something which can (and should) be described is why a certain solution is chosen. If something can’t be made clear through code, it should probably be described in some documentation. Like, why are we using SOAP messages, can’t we handle JSON? Most of the time you can’t figure out why such design decisions were made during development. One of the things which I also found quite useful was the fluent configuration diagram. It described how the fluent configuration was implemented. If you are a newcomer to a project, you probably won’t know what a certain implementation will do and when to use it. Also describing some best practices can be useful for other developers. Hardware and software specifications are necessary most of the time and it’s probably a good idea to describe the main purpose of the different classes/interfaces.

In short, I think it’s good to do the following when writing documentation:

• Save it online (wiki, CMS)

• Make sure there’s (automatic) version control

• Describe design decisions

• Describe why you implemented something in the way you did

• Only document stuff you think is necessary for the reading audience

I do hope to come across some books or whitepapers which describe what I should be writing in these kind of technical (and functional) documents as I haven’t seen one yet. There are some guidelines, but most of them are bloated and have several chapters which you don’t want to read because they aren’t interesting for most people.

Now, off writing some documents again…..