How to write good technical documents

Developers love to code and hate to write documents, but documents are important in IT.

 

We need documents to define how the solution will be built so that coders who enter the scene later in the project can easily catch up.  We need operational and training manuals so the people who are looking after the solution are aided in doing it right, we also need numerous project management related documents but today, I want to focus on those documents that are more technical in nature, and somehow ends up on the coders lap, who usually has no idea how to handle this responsibility.

Firstly, let’s start off by saying that document writing is a skill; it’s a valuable skill that coders should embrace rather than avoid.  It may take you away from your comfort zone, but building this skill alone will helps you advance your career to the next level.  So give this responsibility proper attention and you will see the rewards.

But how does one write good technical documents?  Project managers tend to give this responsibility to coders without guiding them.  It’s a common mistake, and I hope this post will provide the guidance you need.

Get a template

The first thing you should do when given this task, is ask for a template or a similar document from a previous project.  If your company has a good capability maturity, then these templates should be easily available.  If you work in a company that is less mature (or a nastier way to put it, “more chaotic”) and you will need to build the document from scratch.  Its more work, but don’t freak out, the main purpose of the template is to provide a tried and tested format, that’s it, you should not see a document from a previous document as an opportunity to copy and paste 70% of the work, that’s messing up the quality of the document and you are robbing yourself from the opportunity to build up on your document writing skills.

So yes, you need to have a format of the document.  If the document is well formatted, it will be well organised so it’s easy to read and easy to understand.  If your company does not have templates for you, there are plenty of templates on the internet; many of them are free so you may want to go there for a little help in getting started.  Look at multiple documents, and come up with an outline that works for you.

Know your audience

As a coder, it is natural for you to use IT jargon in your everyday language, you talk to other coders in that language, and they understand you and respond appropriately.  When you approach a non-coder and communicate with them, you make that extra effort to use words that “normal” people use so they can understand and respond appropriately.  Writing a document works on the same principle. 

So if you are writing a technical document that will assist other coders in installing that brilliant add-on you created, you can keep the IT jargon.  But if you are building a document for managers or end users, then cut down on the jargon, use simple English and add think about adding a few more pictures like screenshots or wireframes, they love that.

Why is this document important?

Ask yourself what value you are adding, by creating this document.  What’s the purpose of this document?  Once you have an answer to this question, you can draw of a draft and then ask yourself if this document is achieving its intended purpose.  If it is, you on the right track.

Gathering Information

Make sure you have collected all the information and facts needed for the document, use the template to assist you in what type of information you need.

Gathering information may involve digging in the code built by you or other people, but don’t forget to ask other people for information as well, it may be quicker that figuring it out on your own.  Even communication is a skill, it’s a skill that many coders avoid, and this is a good opportunity for you to step away from your comfort zone and work on those skills.

First Draft

With the information above, you should be able to draw up your first draft.  The first draft is really filling out each section of the template with the facts and information it needs.   After that is done, you can focus on the writing.

And now the writing, finally

The first draft does not consider writing style and formatting, at that phase, it’s all about the facts.  Now you need to up the quality with proper formatting.  here are some points to help you:

•   Don’t try to be too fancy with the language.  Keep it simple, clear and unambiguous so there is little room for confusion and misunderstanding.
•  Be consistent.  If you are using the words “Power User” to describe a particular role, don’t change it to “Business Administrator” later in the document.
• Use bullet points and images where ever possible.  it’s easier to read, and important information isn’t lost in the paragraphs.
• Avoid contradicting yourself.
• Keep the document honest with truthful facts, even if it’s bad news.
• Use numbering system so your document can be easily referenced later.

Well, I hope that helps.  If you have any more helpful points, please add it to the comments.  And to those coders writing a document – Good Luck and embrace this opportunity.