Most of us working in IT need to write IT documentation. Technical documentation, system specifications, requirements documentation, or any other kind of IT documentation. Find out the way to write great IT documentation from these tips.
Focus On The Purpose To Write IT Documentation
Before you start to write IT documentation that’s required, you should have a think about the purpose of the document. What is it going to be used for? Who is it targeted to? Why does it need to be written?
IT documentation is used for several reasons:
- To specify what needs to be performed for a project – this may be a requirements document or something similar.
- To specify how a system operates, such as in a support manual or technical guide
- To specify how to use a system, such as in a user manual or user guide.
Once you know what the document will be used for, you should then be able to work out the next step – who the target audience is. Each type of document will have a different target audience, and therefore a different structure and style:
- End users (the people who use the product or system)
- Clients or customers (people involved in the buying or selling process)
- Technical team members (e.g. software developers, testers)
- Non-technical team members (e.g. project managers, business analysts)
I’ll mention the structure shortly, but for now, if you work out the purpose and the audience of the IT documentation that you need to write, that’s a lot of the work done already.
Use An Appropriate Structure For The Content
When you write IT documentation, it can be quite long. Some documents can be as short as three pages, some as long as three hundred. If you had a document that was three hundred pages long, and had no structure or organisation, what would you think of it? How easy (or hard) would it be to read? Not very easy, I would think!
The solution to this is to structure your document in logical sections. This helps break up the content and makes it easier to read, write, and interpret. The structure will depend on the type of IT document you’re writing, but essentially there are a few main sections:
- Cover Page – this usually contains a company logo, the title of the document, and other document properties such as version, author, date, and system.
- Table of Contents – You’re probably familiar with a table of contents. It’s a list of all the sections in the document and the page numbers they start at.
- Summary/Introduction – A high-level or overall summary of the document and its purpose is usually at the start of the document.
- Content – This is the part that will vary depending on document type. It’s the largest section of the document and contains the “meat” or the main information that’s needed for the document’s purpose.
- References and Appendix – Any extra documents that support this one, external resources, tables and other features not included in the main content section.
“So, if there are so many sections and document types, how do I know what to write in my IT documentation?” I hear you ask. Well, there’s a good answer to that. Many companies have standards or templates for each document type. This means you won’t need to work out what headings or section names to use for a system specification document – it should be provided.
If you’re not sure, or if the company has no standards or templates, a quick Google search should provide you with some examples to use to write IT documentation.
Enhance Your Document With Images
I’ve written quite a lot of IT documentation over the years. The main purpose of the documentation, as mentioned above, is to explain or convey a message or information to another person or group of users. Personally, I’m someone who understands things a lot better if they’re in a diagram. If I want to know how systems interact, I would look for a relationship diagram or some kind of flow chart. Many other people are like this as well – perhaps you are too.
As some people use diagrams to help understand something, it’s a great idea to include them when you write IT documentation where appropriate. Diagrams that you should include are:
- UML (Unified Modelling Language) diagrams – these describe a system or process and how it works.
- Flow charts – If you can use a flow chart to describe something you have written, then put it in the diagram. It doesn’t need to be fancy – you can whip something up in Microsoft Visio, or even Microsoft Word (or whichever word processor you use) itself.
- Organisation charts – if your IT documentation refers to a lot of people or roles, then a structured view of them may help the reader to understand.
When you insert them in your document, make sure they fit well. Also, adding captions to the picture is important – it may look like a flow chart, but the reader may now know what it’s about. Adding a caption to images in your IT documentation is a great way to help the reader.