Documents describing a software product are a waste of time?

While recruiting one of our developers he said: In my previous company everything was great except one thing - there was no official company procedure for creating and preserving documentation records per project. Can you imagine this?

Somebody may say “So, what?” I would say no documentation is almost equal to no proof of your development team work or no track of your code writing. I agree developers are usually preoccupied with writing code, code reviews and other development tasks to complete a Sprint in a timely manner, therefore the last thing they can think of, is creating documentation. This is probably due to the fact that in software development companies when we talk about time we actually talk about money.

Think again and accept the unacceptable

Developers are always working towards deadlines and if they work according to the Scrum methodology the maximum time period to complete a Sprint is no more than a month (check if you are Scrum or rather Scrumbut answering the questionnaire). All tasks from the Backlog need to turn from “In progress” to “Done” in just a Sprint time by the software development team according to a common and transparent definition of “Done”, so that leaves almost no time for what they call ‘’administrative work’’.

I know the tension level among developers escalates at some point, especially when they come across to an unexpected issue just before the deadline, let alone to write documentation in parallel with these circumstances. If you consider the statement from above carefully, you would agree that similar situations are dangerous rather in the short-term because you still have time to excuse the delays of the development team.

I will give examples and will expose the results of not creating documentation in the long term. If you think that not completing a project according to the agreed time-frame with the client is a bad thing (note that even in this case you have options to excuse the project development delay), then think what will be the consequences of delivering a project without the client's requirements specification being created, or even worse without a user guide document.

Each software development team is well prepared for regular communication with every single client to be sure that they got the right idea of what the client wants through asking the right questions and creating user stories based on client's answers. A document created as a result of this communication will serve not only as reference for the developer during the whole project development process but will eventually confirm to the client that what they want is what they get and will serve as a proof in a case of misconduct.

On the other hand in each company there is some level of fluctuation of manpower, which is related to a developer being replaced by a new one. How a new developer will become familiar with the project specifics without the relevant project documentation? How will they understand the project architecture, how will they track the project code, how will they prepare themselves for a hand over at all?

You may suggest that another developer from the company will introduce them to the project specifics. But you just said that all developers are too preoccupied with development tasks to waste time on such a time consuming initiative.

How will you keep track of a project code at all without project supporting documentation

Considering the examples above it turns out that you better have a process for creating and preserving project documentation in parallel to the product development process because in the long term this would benefit the company, its employees and its clients all at the same time.

When software developers work on a project there are a variety of documents that could be created during the workflow process supporting the product development. These documents differ depending on the software project complexity and their range in each project phase is based on discussions with developers and a management decision. Still they could be divided into two main parts - those that would support the software development team and those that are aimed to clients (see also our article: How to improve communication with clients).

In addition to that you can always turn to trusted tools that support software documentation creation. Confluence by Atlassian is a good choice as it is connected to Jira – another good option that makes the software development process easier. Consider also other tool alternatives and before making your decision you can answer the following questions that will lead you to the right tool choice:

• Number of input authors
• Output documentation format
• Documentation volume.

Conclusion

To be or not to be a professional software development company? The answer of this question is related to whether or not you have company procedures for software development product documentation and records creation, and if you considered the implementation of such procedures in the short-term.

Escalations that might follow as a result of not creating documentation may cost a lot. Therefore you should think of introducing software development documentation tools and creating the habit of using them in your company. This will require efforts in the short-term but will ensure you a good night sleep in long-term.

What software development documentation creation tools do you use?

Do they ease the development process or make it harder?

Is the time spent on creating documentation giving your company a value?