An article on writing IT documentation - some tips, structure advice and things to keep in mind.

1. complet eit prof essional.com http://www.completeitprofessional.com/documentation/how-to-write-it-documentation/
How To Write IT Documentation
by Ben on February 13, 2012 edit
Most of us working in IT need to write documentation. Technical documentation,
system specif ications, requirements documentation, or any other kind of IT
documentation. Find out the way to write great IT documentation f rom these tips.
Focus On The Purpose
Bef ore you start writing the IT documentation that’s required, you should have a
think about the purpose of the document. What is it going to be used f or? Who
is it targeted to? Why does it need to be written?
IT documentation is used f or several reasons:
To specif y what needs to be perf ormed f or a project – this may be a requirements document or
something similar.
To specif y how a system operates, such as in a support manual or technical guide
To specif y how to use a system, such as in a user manual or user guide.
Once you know what the document will be used f or, you should then be able to work out the next step –
who the target audience is. Each type of document will have a dif f erent target audience, and theref ore a
dif f erent 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. sof tware developers, testers)
Non-technical team members (e.g. project managers, business analysts)
I’ll mention the structure shortly, but f or 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
IT documentation can be quite long sometimes. 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 f ew 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 f amiliar 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.

2. 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 inf ormation that’s needed f or the document’s
purpose.
Ref erences and Appendix – Any extra documents that support this one, external resources, tables
and other f eatures 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 f or each document type. This means you won’t need to work out what headings or section
names to use f or a system specif ication 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.
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 inf ormation 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 f or a relationship diagram or some kind of f low 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 in your IT
documentation where appropriate. Diagrams that you should include are:
UML (Unif ied Modelling Language) diagrams – these describe a system or process and how it works.
Flow charts – If you can use a f low chart to describe something you have written, then put it in the
diagram. It doesn’t need to be f ancy – you can whip something up in Microsof t Visio, or even
Microsof t Word (or whichever word processor you use) itself .
Organisation charts – if your IT documentation ref ers 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 f it well. Also, adding captions to the picture is
important – it may look like a f low 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.
I hope these tips will help you the next time you need to write IT documentation. In a f uture post, I’ll go into
f urther detail on IT documentation – common mistakes, more tips, or anything else that might be usef ul!
Let me know what you think of these tips in the comment section below!
Image: Stuart Miles / FreeDigitalPhotos.net