Technical documentation

Why and how-to

Photo by Steve Johnson on Unsplash

Let me share with you one experience. When studying at the School of Electrical Engineering (Telecommunication) of the Technical University of Madrid, I had the great fortune of working in a University Department in a project for the European Space Agency (ESA). They were very strict about the quality of the documentation we had to provide, and so were the professor that led the work. This was the first time in my life in which I could see the structure of a nice technical document.

Few years later, in my first work I immediately applied the acquired knowledge and I soon started to get advantage of it. Once that the project manager came to my desk asking for a circuit explanation and a possible change in configuration of one of my boards I just said to him: “this is already explained in page 9 of the document”. He was deeply impressed and grateful because such things were source of much trouble. I was also grateful to the previous experience I have had that allowed me to do this way.

However…

Many engineers argue: “I do not document because I don’t like to”. Well, I don’t like sporting activities but I do physical exercise because its good for me. Documenting is good and early documenting is better. How many times I have found bugs in my design when writing down the design or the test plan of a board!

I document because it is good. Period.

Other people (managers, most times) argument: “Documenting takes time”. I ask them: “How much time does it take not documenting?” How much loose time because the designer is no more accessible, or the reasons for the decision is forgotten, or the schematic is not enough, or there seems to be an error, or calculating a parameter in cold state is lengthy or error prone,…

Document early

Documenting early (in a project’s initial stages) has many advantages.

One of them is that yourself and your team can be the first users of the things you write down. The information becomes consolidated in a single place.

Because of that, it has another not so apparent advantage: if you yourself use your written documentation as source of reference, possible errors in it are very likely to be corrected. If instead of that, you write everything at the end of a project, mistakes in the documentation are much likely to survive.

Document structure

The first thing I do when I start a long document is to write down its index. Good index deserves good time to complete and will save you many time later on.

Good index help much the reader and the writer: provides a place (like a hook) where to hang all the ideas you want to transmit.

Introduction

The document’s first chapter is an Introduction. Should have (at least) two sections

1. Purpose. In it, you describe the meaning, the reason of being of the document.

2. Scope, where you explain the context in which the document is valid. This has great importance because it may happen that a document if valid for an old version of a product and you may discover it too late. If you force yourself to write down the scope, you may save a lot of time and energies to yourself or to someone.

Sometimes, when I had not alternate ways or recording, I included a list of Acronyms and definitions. Acronyms are a real barrier for newcomers.

Summary and conclusions

This chapter is extremely important. I learned from my friend Joe that for some types of documents (like those that are written to aid decisions), such chapter should be as early as possible in the document structure. The conclusions are the final goal of an study and you reach it at the end of the journey. However, when this is done, you may help the reader much by placing it as early in the document as possible.

Joe used to do an extra trick: included this chapter in light colors (red, blue) to keep reader’s attention as soon as possible.

Beware that when we write documentation, we do for it to be read, so we have to think mostly on the reader and not on ourselves, the writers.

When this is done this way, following of the document becomes a detailed justification of the conclusions you describe in an early chapter.

Few times I have had to deal with documents that in the last pages they said that all previous explanations, calculations, measurement… were not valid. This is, at least, dishonest.

Interface description

When yo have to describe the interfaces of my board, I always include:

• Functional description, the meaning of every signal in the interface. If some of them are logical ones, describe explicitly the function of High and Low levels. If applicable, include corresponding transfer functions.

• Physical description, including signal and pins in the connector; connector description including Manufacturer Part Name (MPN), a photo and MPN of mating connectors. If possible, include also a URL link to product in manufacturer portal.

• Electrical descriptions: voltages, logical levels, valid ranges, as applicable.

Graphical information is extremely useful.

Review when you finish

Always there are errors in a document when I write it down. All readers of my newsletter know it. I may review the text ten times, if I do another one, I will find some mistake or something that could be said in more proper way. This is more common whey you write in a language that is not your mother tongue.

However, many times I have read documents in which it was obvious that nobody read after writing. “Try to avoid” is all I dare to suggest.

Final recommendations

• Try not to over-document: if something is not relevant, don’t write it down. Baltasar Gracián, an Spanish writer once wrote: “Lo bueno, si breve, dos veces bueno”. (Good, if brief, twice good).

• Manage your documents. Every document should have an unique reference, which should appear in file name and in every page.

• Be precise in document tittle: good tittle helps much, a bad one disturbs much and makes searching more difficult.