Being in IT I have discovered that documentation of processes and individual applications is extremely important. Being someone who writes articles and is working on some book chapters I don’t mind creating documentation. There are a few reasons I think that I actually enjoy writing documentation:
Requirements revisited: since requirements are defined while most projects are in the discussion phases, the ability to outline these requirements and explain them in simple terms for future review is huge. Many times the original (and often revised) requirements are lost in the shuffle and do not get seen very often following their initial draft and revisions.
Help and Aid those around you: creating documentation that answers questions in a simple and straightforward manner will be appreciated by those who need to use the documentation.
Constant change: this one is the work. Since technology doesn’t often sleep and things are evolving all the time, your documentation needs to change as often as possible. Working with your documentation frequently will not only keep it fresh in your mind, but keep you from needing to review all of your documents to get an idea of what needs to be done every time a change is needed.
How is this great?
It keeps your skills sharp. Your writing and communication skills need just as much razor sharpness as your technical skills. Managing documentation will help with both areas. On the tech side, you will need to get as much information about any new features relevant to your organization as possible. Then create or update your documentation. Doing this improves your writing skills and gives some opportunity for wordplay and practice.
Documentation is great…. what tools do you use?
I work with lots of different tools, blogging tools like blogsy on the iPad, Microsoft Word and OneNote, and a tool that is somewhat under the radar, Help and Manual. I have reviewed Help & Manual before and covered some of its features . Since then there has been a new version released and there are new features that I seem to be coming across every day. This post isn’t going to tear through the features of the application but look at why it works for me and how I use it. This will include some features and hopefully be an application that you investigate to improve your documentation.
Help & Manual is a single source editor. This means that you can create your documentation one time and push it out to several different formats including:
- Compiled Help
Help and Manual is an all in one XML based manual building tool. The tool also allows you to import from other formats to collect previously created content. Outside of actual documentation creation, the tool can also create manual parts, cover pages, tables of contents, etc when designing paper manuals (or PDF manuals).
Remember though that the tools you use to create documentation are not as important as the content you create. The goal is to help those around you better understand something that they need or use to do their jobs. Help and Manual is just the tool I happen to use in creating documentation. More information about Help and Manual can be found here.
Why Document… no seriously?
Documentation is something far too few people get behind.. many of us get behind in our documentation, but few really enjoy documentation. To help our customers (or co-workers) better understand things they need to better do their jobs or use a tool or some technology.
Another thing to consider is the view of items which are being explained. For example, suppose there are updates needed for an antivirus application. These are definition updates needed to ensure the application can keep PCs protected from the latest viruses. Explaining why these are necessary to someone in IT might be different from explaining the need for these updates to your grandmother. To accomplish both explanations in one document, you need to think about this from a broad scope. If you explain for all audiences you will not only cover the beginners reading your document, but also the more technically minded members of your audience. If you, however, focus on just the advanced topics or examples using jargon and industry terminology, you will alienate those who may not understand the issue.
Creating documentation for items simple and advanced will also help you learn about the topic as well as work to sharpen your skills creating and delivering documntation others will find helpful.