Write the Technical Documentation for Your Project

In the previous chapter, you saw how to adapt your documentation to the needs of the project stakeholders.

In this chapter, we’re going to look at some best practices and practical examples for presenting your documentation.

A Few Tips and Examples

Start Documenting Before Development Begins

Imagine you’re an architect and going to design and build a house for a family. This family is your client. You’ve met them and asked them some questions—do they need 3 or 4 bedrooms? Do they need a garage? How big should the kitchen be?

You’re putting together a brief in your head. You’ve got an idea, but it’s not 100% clear yet. Jot your idea down on paper! You’ll have to explain your plans for this house to many people: your partners, the builders, the electricians, the plumbers—in other words, everyone working with you on the project. In document format, you need to have a standard, consistent explanation of the type of house you want to build.

It’s all about finding the right balance!

In the words of Scott Ambler, a Canadian software engineer, consultant, and writer, “Only produce documentation that you can manage precisely.” He also added: “Ideally, you should produce something just barely good enough.”

This is the philosophy underpinning the following diagram: the X-axis represents effort invested in documentation, and the Y-axis represents the value obtained. There is an optimal effort point, after which the value of documentation decreases.

The best style choice for your project depends on your specific context:

• Who you are.

• Who you’re writing for.

• What you’re writing about.

Guiding Principles for Documentation

Here are a few main guiding principles to take into account for creating documentation:

• Optimize the reader’s investment. Reading your documentation represents a time investment for your target audience. Is it worth it? Do the benefits outweigh the cost? Remember this before you start. 

• Document the information that is least likely to change. Keep temporary and long-term concepts separate. A document containing rapidly changing information quickly becomes obsolete and is challenging to manage over time. Include information that’s “good to know”—what would the three main takeaways from your documentation be?

• Organize your content logically and progressively—start with general concepts and move on to the detail; zoom in on a few diagrams and explain everything step by step. The content should be set out so that the necessary concepts are covered first. 

• Either cover concepts fully or not at all. Avoid incomplete explanations. If a concept is based on elements A, B, and C, you should first explain these elements, followed by the concept itself. 

• Incorporate examples into the content. Examples help make abstract concepts clearer and easier to understand.

Specific Principles and Examples

Here are a few specific guiding principles and examples to consider when creating documentation:

Avoid Complex Diagrams

Reduce the number of boxes, icons, and arrows to create simple diagrams that can immediately be understood.

Let’s look at a complex diagram that is difficult to understand. You saw these two diagrams in the first chapter:

Bad idea! This diagram is now complicated and difficult to understand. It’s better to focus on the details in different diagrams.

Explain the Data in Tables

Explain the rows and columns in tables, as your readers will need to know what they represent. Describe them first before explaining the different cells in the table. Omitting this is a common professional documentation mistake.

Example:

You should explain what the rows and columns correspond to. For example: “This table describes the different payment types the company accepts for routine transactions and the commission paid by the client for each type.”

“The rows represent the different payment types. The columns show the commission taken by our company and by the payment operators.”

Explain the Axes of Graphs

If an XY graph is presented, you should explain the X and Y-axis as above. Omitting this is another common mistake in professional documentation.

You should explain what the X and Y axes represent: “This progress graph shows the duration of the project in days on the X-axis, and the tasks remaining to be completed on the Y-axis.”

Documentation-Driven Design

If your software hasn’t been created yet, you can start drawing up documentation to make the design process easier. This is known as documentation-driven design.

If you design your software based on documentation, you can easily gauge reactions and change the design before you even start developing.

Use Tables for the Developers

This is an example of a table describing the types of discount according to types of client:

Many stakeholders will use this table, such as developers, system architects, software designers, and database administrators.

Here’s an example of the code that uses it:

//GetCustomerData.txt

/*
The function GetCustomerDiscount shows customer discount for all products
*/

function GetCustomerDiscount(CustomerID)
{
    GetCustomerData(CustomerID);
    rval = 0;
    switch(CustomerID.type)
    {
        case 1:
            // Commercial
            rval = 12;
        case 2:
            // Residential
            rval = 8;
        case 3:
            // Government
            rval = 10;
        case 4:
            // Defense
            rval = 10;
        case 5:
            // Health
            rval = 16;
    }
return rval;
}

Let’s Recap!

• Start documenting before development begins: a software architecture document acts as a much-needed map of your software!

• Follow the “just barely good enough” approach for your documentation. 

• Use documentation-driven design—changing documentation is cheap; changing code is expensive.

• Remember the main guiding principles for documentation:

  • Optimize the reader’s investment.

  • Document the information that is least likely to change.

  • Describe what’s “good to know.”

  • Organize your content logically and progressively.

  • Cover concepts fully, or not at all.

  • Incorporate examples into the content.

  • Avoid complex diagrams.

  • Explain the rows and columns of all tables.

  • Explain the X and Y-axis of all XY graphs.

In the next chapter, we’ll look at some standard tools for documenting your project and its architecture, such as UML and user stories.