How to Write Efficient Documentation

7 tips to help you write a technical specification

Dragos

Dragos

Senior Software Engineer at Softvision
Dragos chose Softvision because he recognized it to be an excellent environment that would allow him to enrich his technical knowledge, and a great place to build his professional career. He joined the Softvision Iasi team in 2011.
During his collaboration with Softvision, Dragos leveraged his software development experience and contributed to many successful projects. His main focus when delivering software solutions are: code quality, enhance end-user experience, “agility” and adaptation to the product changes, and to deliver quality software solutions in time.
Dragos

Latest posts by Dragos

It’s so nice to ramp-up with a project that has good documentation but usually, we are not so enthusiastic when we should write technical documentation.

Almost all projects are documented but most of the documentations are outdated and a significant part of the documentation is not what we can call a “good documentation.” What do we mean by “good documentation?” Would you like to learn to write good documentation? Then let me give you some principles that I discovered by practice on how we can write efficient documentation.

1. Determine the purpose of the document that you are writing

Firstly, it’s important to determine the purpose of the document. Knowing the purpose will help you to figure what information should be included in the document. Having in mind the final goal of the documentation will help you in the following ways:

  • Motivates you. Knowing a specific purpose for what we are doing brings more confidence. In fact, if a document you work on does not have a purpose then maybe you should evaluate if that document should be written.
  • Helps you to have a better overview, a clearer image of what you should do.
  • Helps you to decide what information should be included into the documentation.
  • Helps you to know when the documentation is completed. If you reach the goal, then the documentation is completed.
  • Helps you to evaluate yourself.

On this step, you should be able to answer to the following questions:

Why is this necessary? Why am I writing this? What are the main goals of the document?

2. Determine the target “audience” or reader of the document

Secondly, you should determine who will read the document. It’s important to figure this out, based on the target “audience” of the document you are going to select the style of the document.

  • A technical (developer) person is going to read the document, then use a technical language.
  • A business analyst is going to read the document, then use a business style without adding technical or implementation details.
  • It’s a ramp up document, then use a mixture between a business style and a technical style.
  • It’s a technical proposal, then include only technical details, but take care to keep it high level and not get lost into minor details.

On this step, you should be able to answer to the following questions:

Who is going to read the document? Is it a technical person? Is it a non-technical person?

3. Determine the format of the document

Thirdly, you should determine the template or the format of the document.

If there is already a template that it is used by the client, then you should not lose your time to define another template, USE EXISTING TEMPLATE.

If there is no existing template, then you should define one. This will bring more clarity in the future, and will help in understanding and finding information in the documentation.

Tips and tricks for defining a template:

  • Use a hierarchical structure
  • Keep the structure clean and simple
  • Use more documents (pages in confluence) rather than creating a big document that contains everything
  • Include a table of content

On this step, you should be able to answer to the following questions:

What format/template should I use? Is there already a defined template? Should I define a new template?

We looked at the first three steps, that regards some preliminary, but very important aspects. Before creating the document, we should figure out three important aspects: what is the purpose of the document, what is the target audience, and what template should we use? Having this clear in mind, let’s move forward and create the document.

4. Keep it Short and Simple (KISS)

Be concise and clear!

Use clear terms and do not offer too many details, be concise.

If you offer too many details it will become boring and unreadable and hard to keep it up to date. In other words, it will become useless. On the other hand, you should offer enough details, otherwise it will become irrelevant and unclear.  Otherwise, once again, the documentation would become useless.

To bring more clarity, it’s recommended to use tags, schemas, images, table

WARNING: Do not use images, tables, schemas that are not self-explanatory and needs to be explained in text, they are useless and do not bring clarity. The main reason to include visual components is to bring clarity.

Be abstract!

Abstract means a summary of a text, scientific article, document, speech.

Something that concentrates the essential qualities of anything more extensive or more general, or of several things; essence.

A summary of the main points of an argument or theory.

Let’s take an example to be clearer. We want to explain the following piece of code:

Image1 –  Code Sample

This can be documented like this:

  • If the user is not null and the user role is not null and the user role id  is 6 then gets a new instance of BankAccountRepository, goes to the database and from BankAccount table selects all the rows that have the UserId equal with the id of the use object and the UserRoleId equal with 6.

Or can be documented like this:

  • For an existing “account operator” user returns the assigned bank accounts.

Which is the best option and why? Obviously the second option it is concise and clear.

You should not include magic numbers in documentation (or in code). Figure out what does it means… In this case it refers to a specific user role which is “account operator”. Use the role description rather than a magic number.

You should not offer too many details. The implementation details (null checks) are not relevant. We can rephrase this by something like: For an existing “account operator” user. Also, it is not relevant that creates an instance of a specific class, and what table do you use to get the data. We can rephrase this by something like: returns the assign bank accounts.

5. What you should and should not include

Ensure you understand the technical level of people working on the project.

Do NOT use technical terms that others cannot understand or may not know.

Let’s take a look at some examples. If you should create a ramp-up document:

  • This module certifies accounts. => Problem: For a new person, it is too vague a term like certifies accounts. What does this mean?

Tips: Define a glossary of terms, and point to that glossary, otherwise do not use terms specific to project business logic if you intend to use that document for a software developer or a QA ramp-up.

  • This module handles account reconciliation. => Clearer but still requires explanations. For a developer, that does not have financial knowledge a term like an account reconciliation it is confusing.
  • The uses of this module will be able to verify that the total incomes for an account that matches the total outcomes of that account. When the incomes match the outcomes, the user can confirm that the account can be reconciled. This is the certification process.

Define a glossary of common terms and direct readers to that document.
But do NOT include definitions of programming technical terms or of other stuff that can be found on the internet

  • Do not explain OOP principles
  • Do not explain a known algorithm
  • Do not explain a known design pattern

Include details about input and output formats and validations

  • Json format and Json schema
  • Date Time must be in a certain format
  • Parameters are mandatory or options
  • Parameters should have some default values

Include information about handled errors and the error format

  • Include information about how the errors application catches and treats the error only if this is done using a certain pattern.
  • Provide information about what error code is returned, and describe when this is expected.
    • Ex: http status code 505 when the DB server is down.

Include class diagrams, flow diagrams and any other diagram that brings clarity and is explanatory

6. When to include code samples

As a general rule, code samples should never be included for describing what a method or class do. The code may change and the documentation became outdated.

You should include code samples:

  • When you what to outline a certain rule on the project
    • Coding standards
    • Method Naming
  • When you want to outline how a certain Design Pattern is used in the project

7. Conduct a final review

Before considering the documentation, process completed, you should do the following steps:

Review your documentation

  • Read it two or three times
  • Ask someone else to review it and clarify the issues that are not clear
  • Remove the garbage
  • Are you pleased with your document?

Answer the following questions

  • Do you use clear terms?
  • Does the documentation communicate a clear image/overview of the module?
  • Is it concise?
  • Is it short?
  • IS THE PURPOSE FULFILLED?

References

Howard Hendricks – Teaching to Change Lives
Haddon W. Robinson – Biblical Preaching: The Development and Delivery of Expository Messages

Share This Article


Dragos

Dragos

Senior Software Engineer at Softvision
Dragos chose Softvision because he recognized it to be an excellent environment that would allow him to enrich his technical knowledge, and a great place to build his professional career. He joined the Softvision Iasi team in 2011.
During his collaboration with Softvision, Dragos leveraged his software development experience and contributed to many successful projects. His main focus when delivering software solutions are: code quality, enhance end-user experience, “agility” and adaptation to the product changes, and to deliver quality software solutions in time.
Dragos

Latest posts by Dragos

No Comments

Post A Comment