There is an art to documentation. As a Systems Architect, one of the key parts of my role is being able to create documents and guides for technical and business processes. Whether it is an existing process, or a newly developing concept, the method is most always the same.
What is different in creating documentation is the style of writing based on the audience who will receive the document. There are considerations for the medium that is is delivered (hard copy, online, mobile device, audio, video) as well as the most important factor which is the knowledge and skill level of whomever will consume it.
Have you ever been told “write it so that a monkey could do it based on your instructions”. This is an insult to both the writer and the consumer of the document. If it were true that we were meant to write if for a “monkey” to do it, then really we would need to have a monkey create it in the first place as they would best understand the audience.
Now back in the world of human documentation, it is a little different. We should write with a level of detail that is appropriate for each situation. I’ve learned over time that less is more (although I can still be wordy with writing). Here is an example:
Option 1: Hover over the My Computer icon which is on the desktop and then using the right mouse button, right-click and on the menu, choose manage which will bring up the Computer Management console.
Option 2: Right click on the My Computer icon and select Manage, or go to Start | Run | compmgmt.msc
While both achieve the same result, the second option provides two ways to do the same task with nearly one third of the word count. If you write more concisely, there is a better chance that it will be read and understood. Too many words will cause the reader to skim and skip what may be key information.
Next up is the visual aspect. Images and visual components help to both excite the eye of the reader and to provide specific examples which can better guide them to the result.
If you write for a technical audience, you have an interesting challenge. Quite often the audience believes they already know as much as they need to know, and can be very particular (aka picky) about what information they want to gather from documentation.
I highly recommend that you seek out examples of documentation and read up on DITA and other great writing tools to help you towards creating good documentation. There is a great article at Publishing Smarter about Minimalism and good documentation I think is a great start:
In fact if you have the opportunity, I would suggest getting in contact with Bernard and his team at Publishing Smarter if you are keen to get involved in documentation and technical writing. They produce great results and have guided many people like yourself and myself towards creating great products.
As a final note I will leave you with these tips that I find have given me good guidance:
If you want to be a good speaker: listen.
If you want to be a good writer: read.
And lastly, while practice may not make perfect, it sure helps get you closer!