In every project, a lot of knowledge is stored inside team members’ brains. But it’s not the safest place to keep valuable information. So, project documentation is key.

• The high effort that goes into documenting too much detailed information leads to the docs becoming outdated and, eventually, abandoned.
• Inadequate structure, language, or level of details means readers won’t benefit from the documentation, and again, you’ll abandon it.
• Low quality of information means readers won’t be able to use it because they won’t trust it.

In this article, I’ll give you some tips for the successful creation of the three most common types of documents (and you’ll probably be able to apply them to other document types, too.)

Consider the costs of documentation

I’ve seen many projects in which documentation is treated as something cost-free, so no time and resources are allocated to do it. But writing a good piece somebody else will benefit from requires a lot of time. So, if you’re a project manager, you should take it into account when planning your budget and schedule.

Also, because there’s no time, documentation is most often a low priority, because it doesn’t bring direct value to the product. And because the Agile Manifesto says, “We value [..] working software over comprehensive documentation”, it’s easy to excuse such an approach.

But hey! It’s not like that at all. The Agile Manifesto doesn’t neglect the value of documenting things. People mostly skip the last sentence: “That is, while there is value in the items on the right, we value the items on the left more”.

Think about users and their needs

Sounds obvious, but it turns out that it’s not so easy to jump into somebody else’s shoes. Before you start, try to predict who and when will need the knowledge transfer you’d like to share. Don’t try to give a huge pile of details at once just because it’s easier that way. Here are some questions I use to keep my focus:

⦁ What language should I use? Is the user a technician, developer, programmer, or a business person?

⦁ What goals will the user want to achieve when reading this document?

⦁ Did I give enough information to achieve those goals?

⦁ Is it useful and accessible?

⦁ How much effort will I need to put to reflect the changes in the project and maintain the document?

⦁ What will be the optimal structure to avoid the need to read all the pages just to be sure that you haven’t missed any vital information?

A hint to the last one: the table of contents is just the beginning, but you could go further and equip your documentation with additional indexes (it’s normal to have multiple indexes in database systems — why not use them in documentation?).

Diagrams and charts are awesome

People like images and they really help understand things much faster than reading through infinite docs. Diagrams are also extremely useful in presenting highly abstract knowledge, especially if you want to make sure it’s complete.

There are standards and guidelines on how to create diagrams, like UML or BPML. You will surely find them useful, and they’ll help you create great diagrams. Just remember not to end up a diagram-specification-nazi.

If you feel limited by the standards, be creative, extend them, or even go completely freestyle to make them work for you. Use colours and organize things logically in a 2-dimensional space. The only thing that matters is to make the document as pleasant to read as possible.

Control the level of details, plan the structure

Is the reader always interested in all the details and quirks? Think about the user and his needs. Always try to find what level of detail they will need to achieve their goals.  

Of course, this approach has some drawbacks — you’ll probably need to duplicate some information and write it down several times with varying levels of detail. This means you will have more information to track and maintain when something changes in the project. But from my experience, it’s better to put some extra effort and gain much more — useful documentation.

Your goal is to make it easier to reach the information the reader is looking for. How would you divide a user manual? You can organize it by features, modules, level of user experience (e.g., first chapter for a quick start, the rest for advanced use), or user roles (separate sections for each role).  The same applies to technical docs, but the possibilities are even greater. Think through the use context: maybe you need to extract a chapter for emergency procedures? Deployment? Team onboarding? 

Try to group information together when there’s a logic behind it. Don’t make the structure too flat or too deep. Consult it with the users.

Don’t follow the template at all costs

If you search for “Software Requirement Specification” in Google, you’ll surely find a lot of useful templates that could help you out in the beginning. But they won’t necessarily fit your context. You could end up focusing on aspects that don’t always matter to you. Or are simply not the right format for your project. 

For example, use cases are great for describing system behaviour, but I’m not sure if it would be my first pick for describing a system that’s data-driven and has a lot of similar CRUD-like features.

Make it part of the process

The best way to enforce the maintenance of proper and updated documentation is to incorporate it into your development process right from the start. The document will then not just be invented to meet your contract requirements, but it will be the result of a real need, and will instantly be verified on the “battlefield”.

From my observation, involving quality assurance in taking care of requirement documentation works really well:

•Testers motivate developers to cover the documentation, so it’s in their interest to keep the document up to date if they want to deliver the right product.

•Testers have to know what to test so they need knowledge about what should be delivered in the final product.

•Testers have to protect the product against regression (regression = unexpected bug emerged in the original set of features after modification or introducing a new feature), so they need to keep an exact register of all features.

• Putting testers as close as possible to the source of the requirements helps reduce the risk of turning the Project Manager into the only source of truth. It happens quite often in small companies and causes a situation when nothing can be delivered to the customer without the acceptance of the Project Manager. It shouldn’t be their responsibility!complete, precise and updated.

This approach is naturally becoming part of the process as it is in the best interest of the QA to keep the requirements complete, precise, and updated.

Learn and invest in your software engineering toolbox

Software engineering is recognized as a separate branch of computer science. There are a lot of interesting publications on the subject. Expand your toolkit, learn new methodologies, and get familiar with good practices. That way you will have a broader perspective of possible approaches and will be able to choose the ones that fit your projects. Here’s some basic knowledge.
When it comes to requirements, you can divide them into functional (features) and non-functional (quality) ones:

• Functional requirements strongly depend on the project, so there is no generic template. But software engineering suggests some forms of requirement description: use cases, mockups, user stories + definition of done. (Note that a user story without an exact definition of done is just an invitation for further discussion, but it can be the right form for a basic description of the project features.)

• Non-functional requirements were described in the ISO 25010 standard that proposes a closed list of areas like software security, the safety of use, maintenance, service availability, recoverability, availability for the user, performance, interoperability, extendability, etc.

Software architecture is even more complicated (it strongly depends on the project type and scale), but we can also find a systematic approach. The 4+1 Architectural View Model proposes describing the software architecture in four aspects, each one for the different reader:

•Logical (user, business stakeholder).

•Process (integrator, system analyst, database engineer).

•Physical (system administrator, integrator).

•Development (software developers).

Each of those aspects is supposed to be connected with use cases (that’s the “+1” layer) taken from requirement specification, which should guarantee the full coverage of requirements by the system architecture.

Test it!

Testing a document? Sounds crazy, right? But if you want to make sure that your deployment guide is complete and bullet-proof, just ask some people from outside your project to deploy the software by using only your docs. You’ll be surprised by how many things are missing

In the case of system description, try to figure out use scenarios for the document and involve people outside of your context to verify them. Check if your document helps them out and what’s missing to accomplish the scenario. It might be as simple as “Adding a new plugin to your ecommerce web application”.

Do you really need it?

Remember that you will need to put in a lot of effort to create useful documentation, and you will also have to keep it up to date all the time. Otherwise, readers won’t trust your documentation and will just stop using it. Outdated documentation might even bring you more harm than none at all. That’s why you should carefully choose the scope and even reduce it when the docs become too fat.

Alternative: Self-documenting solutions

Developers say that good code explains itself and doesn’t require comments. And it’s not only about code: there are specific tools, techniques, and approaches that can decrease the size of the documentation by bringing interactivity.

•A good user interface can reduce the need for keeping a user manual.

•If your project involves complex processing under the hood, consider exposing it in the user interface. The knowledge about business rules coming from the application has a higher chance to live on than some descriptions in doc pages.

•The documentation of deployment configuration can be significantly reduced by using Infrastructure as a Code and Virtualization techniques (Ansible, Chef, Docker Composer, Kubernetes – whatever suits your project).

•REST APIs can often be self-documented by using tools like Swagger.

•BDD-like automated tests are great for maintaining up-to-date requirement specification.

•Code repository + pull requests synchronized with issue-tracking software reduce the effort of maintaining the changelog document. A smart choice and setup of tools will do it for you.

I hope that at least one of these points will inspire you to improve your documentation processes. If I’d have to choose one thing worth remembering from this article, it would definitely be “try different approaches and create your own path”

Background picture source: Photo by  Alejandro Escamilla on Unsplash