The directory mapping must be reduced in writing for future references. The following are proven tips when creating IT documentation. The same principles apply when building directory mapping documents.
- Document with pictures if possible
The old adage a picture is worth a thousand words means that by using pictures to augment your text, you can minimize the length and complexity of your documentation. System users like having pictures, diagrams, tables, and bulleted lists for quick reference.
- Give examples
Examples are an excellent way for end users to quickly grasp concepts that they may not fully understand. It is also a good way for an end user learning new software to sit down and tackle a new challenge more easily.
- Don’t presume to assume
Even if you know your targeted user base, your documentation needs to be written so that anyone with only basic computer skills can read it and learn how to properly use the system. Step-by-step instructions should be provided when possible, but consider placing them in an appendix, a separate chapter, or making them available via a hyperlink to avoid clutter. If you are doing the documentation, change your mindset so that you place yourself in the shoes of a new system user. That can be difficult to do at first, but if you pay attention to details and fully document all features and functions, you can create documentation that doesn’t assume that the user can figure out information and procedures you have failed to include.
Don’t assume that your end user understands all of those acronyms that litter the IT landscape. The first time you present a new acronym, detail what the acronym stands for.
- Anticipate problems
When testing your system, you should have tried your best to break the software any way you could. If your software has known issues (developers like to call them issues; end users call them bugs), document a workaround and provide it to your users and the help desk. You will not only save a lot of frustration for the end users but also a lot of extra calls to the help desk.
Document the events that are inevitable during the lifetime of any long-lived system:
- What workarounds are available while the system or network is down?
- How do you recover from a server outage, a hard disk crash, or database corruption?
- How does someone who knows absolutely nothing about your system get the system up and running again?
Your documentation should anticipate these problems and provide a detailed plan and instructions for system recovery.
Will the person who replaces you know where to find your documentation and any purchased vendor application documentation? All of these documents should be neatly organized and stored together in a safe and known place.
- Test your documentation
Sit down and follow your own instructions. If you are documenting the building of a server, a network, or any other IT system, start with a clean partition and build everything from scratch. You will undoubtedly discover that you have left something out or that some of your instructions are unclear.
Work with an uninformed but committed co-worker to get feedback before you publish. Let them test out your documentation.
You will be amazed at what you will learn when you sit a person down to work with your software and documentation for the first time. A lot of features of the software that are obvious to you will not be so obvious to someone who is honest and willing to work with you. Watch closely what your guinea pig does while navigating your software. Ask for feedback and take notes.
Leave a Reply
You must be logged in to post a comment.