10 tips on making effective documentation
One of the things that Integration Engineers are asked to do is create documentation. But as we all know, many times documentation is the last and poorest part of a project. Developers and programmers don’t generally like writing documentation, and are generally considered the most qualified.
In comes the Integration Engineer to make the system work. Producing effective documentation at this point is important. We want to make the system work, and then hand if off to the team that will support it. If we don’t create effective documentation, this last step can never happen, and we will be unable to undertake new integration work because we are still supporting the first one. And if we are a contractor, we need this even more.
1. Have a plan of what you want the reader to understand.
When you start taking notes, you won’t have this plan, and that is okay. Notes are mostly for yourself. 
But by the time you start to create a document that you want someone else to read and understand, you will need to have a plan on what the reader will take away from the document. Ask yourself, “Is this a ‘how to’, or a ‘how works’ document?”
There is some overlap and subcategories for these two general types, but in basic if you are documenting how to start the system, or documenting how the parts of the system work together, you will use a different approach. There will be some examples in the ‘how works’ document that will be like the ‘how to’ and any good ‘how to’ explains some of ‘how works’ that is inherent in the doing. But these two approaches produce documents that look very differently.
2. Break the document into sections.
Unless your document is less than a paragraph, it should have sections. If you don’t know what those sections could possibly be, keep reading. If you followed tip #1, then you should include a section in your document relating what the reader will get. The important thing is to logically organize your document into sections that allow the reader to get the most information from it, and to make it usable as a reference.
3. Include the location/source of any tools that are used.
A good way to avoid the call at 2 AM is to ensure that your documentation includes any tools that are needed and how to get them. Sometimes this won’t mater, the interface is the browser and the editor is VI. But when that is not the case, you will want to reference any and all tools and how to get them. You will probably want to include this near the top of the document so that the reader can know what they will need before spending hours only to find out they needed a proprietary widget that takes 2 hours to install.
4. Include Levels of access needed to do tasks.
Just like tools, any specific access need should be documented. If a a DBA is needed to complete a task, then say so up front. This will not only prevent you from getting a call at 2 AM, will prevent frustration to the reader, and may prevent accounts from getting locked and other security measures from activating when people with less access than you try to follow you instructions.
5. Include Screen shots.
A picture tells a thousand words as they say, and adding screen shots to your documentation helps your readers to not get lost and can show them something difficult to describe. So take screen shots as you go through the process and then include the ones that help guide your readers.
The two places to include screen shots are; Where the description is insufficient to keep the reader from misunderstanding. And when the interface the reader will see changes, each new page so to speak.
6. Include code samples
Like a picture, sometimes a snippet of code is the best way to explain a process. Especially if you are documenting a mapping or integration procedure that involves coding. But even if you aren’t including code snippets can help explain to people familiar with reading code better than any explanation.
If your audience is not comprised of code readers, you might replace code with a flow chart or diagram to visually explain the process in place of code samples.
7. Include real life examples.
If you have ever read a legal document, you know that excessive abstraction, (party of the first part), can be detrimental to comprehension. Sometimes it is easier to say, “Fisher is a good example of an bidirectional EDI integration set-up.” And then explain why. Anyone familiar with Fisher will know immediately what you are talking about, and those not, now have a place to look and find one. And you avoid multiple sentences starting with, “The Supplier.”
8. Include check-lists.
I have found that many of my ‘how to’ documents can be reduced to a check-list for the experienced user. 
After reading the steps for setting up a vendor 15 times, I just need to be reminded of the steps. Now my explicit document with pages of screen shots and examples becomes a stumbling block. I may miss a critical step because I am trying to page past the explanation that I no longer need.
So after all of the explanation is over, a check-list or overview can be an effective in making your documentation useful even after the user is familiar with the process. This will keep the document in their hands for when something odd happens, or when someone new needs to follow the process.
9. Follow your doc.
An important part of prof-ing your documentation is to follow it yourself. Don’t just write down the steps from memory or notes. Even if you are really really sure. You still need to follow your own documentation, and do exactly what it says to do. While you do this you need to pretend that you only know what the document says.
When you find places in the document where any knowledge is assumed, then you should at least reference that fact. If My document says, “Now log-in to the database with system account.” I need to mention that this step requires a system account on the database. And I need to reference this at the beginning of the step. You will probably not want to include the user name and password into the document for obvious reasons, but if someone following your document gets halfway through a step and then discovers that they need your level of access, expect a call.
After you have followed your documentation, you may want to get someone else to follow it and see where they stumble. This is even better than following the document yourself, as the user will not know the things your learned on the way unless you have included that in the documentation.
10. Save a copy
This may or may not be obvious. Saving a copy does two things; First, it makes sure that no network or backup failure on the file server will lose your documentation. You will never have to re-do all of the work. Re-done documentation is rarely better if the first has been lost. Second, you will be able to reference your documentation for future projects, use them as templates, examples of your work, and so forth.
Summary
This is not a ‘how to’ of writing documentation. Each company will probably have an established way to document things, even if it isn’t followed. While following that process will produce documentation, adding images, snips of code, requirements and so-forth will make your documentation stand out as authoritative, and excellent. And it may also keep that phone from ringing with questions for clarification.
Subscribe to "The Integration Engineer" by Email
Find out about the tools and services available at The Integration Engineer's Consulting site.
