Don't Drown in Documentation

In software development, how much documentation do you need?

My answer: Just enough.

I do not hate documentation, I am actually pretty good at organising and churning them out. But then I began to feel it was an exercise in futility. We could not keep up with the pace of change and it became quite cumbersome to maintain.

Now there are many who may disagree with my stance, but hear me out. I am not advocating the eradication of documentation, but asking you to really question how much documentation you or your team needs that isn't already being created as part of other steps in the natural process of developing software.

Code

If you and your team write code well, I argue that in itself is great documentation. If code is kept to a consistent standard, organised and is easily readable, you have in your hands excellent documentation that is always up to date. Even consider not having comments in your code, which, when not well maintained, is usually already wrong. The running code never goes out of date.

Tickets

As part of your development, you might be creating tickets for features or workpackages. These could be stored in systems such as Redmine or Atlassian's JIRA. They also act as great historical documentation and within them usually are the reasons why certain decisions were made at crossroads during builds. Even tickets capturing bug fixes hold conversations that may have resulted in the build or rebuild of features. If a ticket is used to detail what is needed to be done, any relevant diagrams and visual aids should be attached to them as well. Keep up with consistently capturing your requirements in tickets, you need not create them elsewhere.

Test Scripts

Test scripts are an incredible form of documentation. If they cover all paths and all aspects to test your build, they accurately explain how your software works. If you follow Test Driven Development (TDD), these scripts are also always up to date.

FAQ & other Must-Do Documentation

Questions that keep coming up again and again, requiring the same answers that rarely change, highlight the need for documentation. This is what needs to be compiled in a quickly accessible resource like an FAQ. It could be stored in shared spaces such as Redmine Wiki or Atlassian's Confluence. Again, I would advocate that such documentation only cover what is asked for frequently.

Training

After all of the above, I am aware that this may cause a learning curve. Teams will need to be trained to understand this new way of working. That they aren't looking for word documents stored in a shared drive anymore, but need to creatively explore other sources, to find the information they need. It may mean initial work in the beginning, but if it saves you time from creating documentation that no one ever reads, it will give you more time to deliver quality software to a deadline. Training, as an investment, is never a bad thing.

Thank you for reading. Please feel free to share your thoughts and advice as I am also keen to learn and improve my way of working.

I have specifically left out documentation that is customer facing, as that should ideally not be written by developers, but by someone who fully understands the customer's business and can communicate in their preferred terminologies.