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.
Top comments (11)
It's been my experience that people are happy to dump information into a wiki but many will rarely, if ever, update it or clear out obsolete parts.
I'm not really sure what to do about this part short of trying to make it as easy and light-weight as possible to do, and I suspect (but haven't tested) that the best solution to this is wikis based on a VCS where the users can download all the files to their own system, and use their existing local file editing tools, rather than a web interface.
Confluence in particular seems very heavy to me since Atlassian removed the markup interface and made it all use the rich-text editor.
A process that could help with wiki-based documentation would be to have every single article on the wiki automatically marked as out of date on some regular schedule.
Active articles would quickly be edited and acknowledged as up to date, whereas abandoned articles would either be removed or left marked as out of date.
This sounds like a good idea, at least to start from.
I've also considered something like a bot that would give people "A Doc a Day" -- mailing people a single page that they can then either update, delete, or mark for a more involved look.
Delivering software being system component, more engineering level documentation is often expected. Customers/peers will request: requirements/features list, overall high-level architecture, explanation behind design decisions, API description, various reports: performance reports, test coverage report.
Requirements regarding documentation differ from one industry to another. Unfortunately, there is no general rule how much is enough.
If you're delivering an API then one would expect the API to be documented. However, if you're delivering code then the expectation should be different. That is, there's no implicit requirement to produce extensive docs just because you have a code deliverable.
The software industry is immersed in other industries. The product is not always a complete, end user facing, application or system. We are delivering parts of a solution and it is necessity to explain an idea behind the code. This enables other engineers to create more efficient systems.
What is more, I do not expect to receive a full blown word document each time. Describing simple algorithms in few sentences of a readme, uml diagram or presentation is often enough.
Providing an explanation why we did things certain way is a part of engineering work.
I agree with this. Code documentation is best reserved for things that aren not self-explanatory in the code. They are also only a second resort, when refactoring doesn't fix the problem.
Documentation is however good for cross-module, or highly abstract, concerns in the code. Sometimes the flow of the code just doesn't capture the big picture. Comments on the big picture can help somebody new to the code. It tends not to get as outdated as quickly either, since the high-level concepts change at a slower pace.
As an expception, if the deliverable is a library, one would expect the API to be extensively documented. The users of the library shouldn't be expected to read the source to understand how to use the API.
The importance of that paragraph. Internal documentation all of this is spot on.
Externally, if your users have to work, forget getting them.
Absolutely!
Shameless plug (but totally relevant!): Please have a look at codestoryapp.com. It was designed to address what I think are the main issues of code documentation.
For me, unnecessary documentation is an overkill. If a code speaks for itself, there isn't a need to document it.