The tricks are simple yet in fact, surprisingly few developers use them. The tricks are inexpensive yet many authors prefer to ignore them and lose their time and money instead. Here you will find 12 ways to make your work on product documentation faster, more efficient and less time consuming (Efficient User Manuals Creation). The majority of techniques are applicable to most of documentation development tools including Dr.Explain. Ready to boost your productivity? Let’s go!
#1: One Source – Multiple Formats
This one seems obvious, but still, many products display discrepancies between online and offline manuals, between PDF and HTML versions of the manual, between the printed brochure and the in-product help file.
Documentation of your product must be straightforward, explicit and water-fast – no double meaning or contradictions between various versions of manuals are allowed. And even more important is the time saved thanks to an instant generation of all formats at once. Hence the rule #1 – use the same source to generate all versions of your documentation. Just choose an authoring tool that allows exporting to different formats and enjoy increased productivity!
#2: Keep Raw Versions of Pictures, Diagrams and Graphs
While modifying the text of the manual is relatively easy, screenshots, diagrams, illustrations are not that editable, especially if you don’t have source files anymore. Just one new button in a dialogue box means you need to rebuild the screenshot from scratch adding callouts, labels and designations so to reflect the change. Too much of work for just one button, isn’t it?
Keeping source files for every screenshot and composing complex diagrams from simpler parts (also with sources) means you can adjust any illustration in your manual way faster and preserve consistency.
#3: Start Using Those Hot Keys Already!
While the mouse is certainly a very convenient human interface device, it is way slower than the keyboard in many aspects. Studies show that executing commands using the keyboard is extremely fast but only if the user knows keyboard shortcuts. A user spends the biggest portion of time on remembering the proper keyboard shortcut. This is literally the slowest part of the process. So the better you know hotkeys, the faster you can be.
Regardless of the application, you are working with when building your manuals, it undoubtedly provides shortcuts for most of the common operations. Learn these shortcuts and easily boost your productivity twice or more!
#4: Define and Use Global Text Styles
Any help document always has some repeating semantic blocks: normal text, highlighted text, code samples, warning boxes, headers, sub-headers, links and image annotations. Having predefined styles for each such block is good for two reasons:
- You easily maintain your corporate style across manuals regardless of how many people are working on them.
- You can easily change the appearance of the entire manual by quickly changing the styles, not by sifting through each document and changing semantic blocks appearance one by one.
#5: Use Snippets Instead of Repeating Values
The common plague of many help documents is repeating values. Product names, file names, menus, controls, repeated directions to a reader (“Press the ‘OK’ button to close the dialogue”) are just a few examples of such values. It doesn’t save a lot of time to just place a snippet instead of the value itself. But snippets do save loads of time when it comes to make changes in the manual.
Not only should you read through the entire text of the manual and find every occurrence of the fragment that requires change. You must also make sure the replace didn’t break anything. The process is terribly time-consuming.
And it goes without saying, snippets (or macroses, or variables as we call them in Dr.Explain) are much more convenient.
When you need to make a change, you just make it. Once. No need to proofread all the text then and waste hours.
#6: Automate Tables of Contents
Hell, its 21st century! Every – EVERY – more or less advanced text processor has automatic ToC creation. Not to mention specialized help and manual building tools. Dr.Explain is not exclusion. Automated table of contents means the manual remains consistent, and the links point where they should regardless of whether you added new sections to the documentation, removed a section, or merged two into one.
#7: Automate Everything! – Efficient User Manuals Creation
…whenever you can. Syntax, broken links, duplicate texts or sections, consistency, availability of resources, missing files, wrong IDs – check all of this. And automate the check if the tool allows. This saves tons of time, not to mention help you avoid many problems with documentation.
#8: Use Color Coding and Statuses
Changes in really large help files especially co-authored by several persons are hard to track. Which sections are ready to publish? Which ones still require attention? What are TODOs for this particular section? To quickly see the status of each part of the manual, use colour-coding. It makes things much simpler and you don’t have to spend a lot of time trying to figure out what is done already and what still waits for its turn.
In addition to colours, you can assign tags, labels and statuses to sections and documents of your project. Indeed, when you take a look at a page of the manual and see “APPROVED” or “INCOMPLETE” marker, you clearly understand what’s going on here. Also, the markers allow you to run a search through the entire project to find all documents in the manual that are “INCOMPLETE” or have something “TODO”.
#9: Compile the Manual Every Time You Build Your Project
Many tools for documentation creation offer some ways to automate compilation of the manual. It’s a good idea to link the compiling of the manual with the building of your product. Use command-line execution to export your help project into the entire set of help documents (see Tip #1) every time changes are made in the product itself. This technique helps you to keep your documentation up to date and actual.
#10: Use Version Control System
Any version control applied to documentation enables all the advantages: access control (crucial for co-authoring), safe commit of changes, control over changes made into the manual, maintaining multiple versions (forks) of the manual, registering and controlling text editing tasks, creating reports and more. Yes, such systems require certain changes in the way you approach to creating manuals in the first place. But overall boost of productivity and safety of your work will cover the expenses pretty much quickly.
#11: Comment Every Change You Make
Do not just make changes – leave comments on what you changed and why. In the long run, it helps a lot to keep track of how the manual evolved over time. In details, that is.
Make your comments sensible, though. Do not write “Changes in the QuickStart section”. Write “Added a screenshot of the Open dialogue in the QuickStart section” or “Fixed a typo in the 3rd paragraph in the QuickStart section”. Being specific pays when it comes to reviewing changes, or rolling them back, or comparing different versions of the manual.
#12: Backup Your Work
The last, but not the least is regular backups. Countless hours (days and even years!) of work were lost due to the carelessness of developers. Don’t fall a victim too. Daily backups can save you from going back to square one in the development of your product documentation.
Conclusion
Overall, these methods can increase your productivity a lot, while making your work over documentation safer and easier. Note, that all of them are relatively easy to implement. The hardest part, probably, is to start using them in the first place. So, here is the final tip for you: implement the above methods one by one. And eventually, you will end up using them all and efficiently composing easy-to-read and informative manuals for your products and systems. And of course, following the above tips becomes much easier when you use proper help authoring software, like Dr.Explain. Every technique we have reviewed here (and many others too) are already embedded into the workflow of this tool.
Author Bio:
Dennis Crane is the team leader of Dr.Explain software team. He mostly specializes in help authoring software development and in software documentation methods. The area of expertise includes UI and UX, user support and relationships, product and project management, and IT business management.
