DOCUMENTATION | TECHNICAL WRITING | SOFTWARE
Important Questions to Ask Before and After Writing a Document
A Comprehensive Checklist to Avoid Regrets and Improve Project Management
“Trust but verify.” Ronald Reagan, 40th U.S. President
In everything we do in life we either make seat-of-the-pants decisions on the basis of emotions, past practice, and untested assumptions … or think serenely before we act and ask a number of crucial questions to understand what the current facts are.
The first method usually leads to disappointment or worse. The second method brings peace and success.
Writing a technical document is no different.
I forgot the number of times in my long career as a professional writer when I regretted not asking relevant questions before hand and getting straight answers.
Especially if you are working in the high-tech sector (like for a software company), such questions become indispensable since errors are costly.
Why is that so, you may ask.
One reason is, things are always hectic in a software company. The market competition is immense and every project team tries to release the product yesterday to beat the competition.
That’s why documents are usually written, updated, and reviewed at the last moment. Usually writers do not have the luxury to take their time, backtrack when there is an error, and try it again from scratch.
Another reason is the complexity of most technical document projects. Everybody feels the time pressure. There are so many actors all trying to keep their heads above water. There are new software builds constantly released and the documentation department is expected to keep up with such a furious pace.
Writers are expected not only to work quickly without errors, but also understand and learn all the new features of the product.
Within such a pressure-cooker environment it helps tremendously if writers go through a checklist to make sure nothing is missed.
Document Size
For example, even something as straight forward as document size can lead to problems if it’s not cleared up in advance.
Up to that date you might have produced all documents in 8.5” X 11” dimensions.
But without telling you about it, someone might have decided that the next quick start guide will be 6” X 9”.
A rude awakening will be awaiting you when it’s time to deliver the document if you just assume that it’s going to be again an 8.5” X 11” document.
Converting an 8.5” X 11” document into 6” X 9” in the last moment may not be as easy as you assume, especially when images, screenshots, and mathematical equations are included in the final product.
There are so many mines in the mine field if you are not awake and vigilant about such risk factors.
Fonts
Fonts, for example, are an occasional source of anxiety.
If you are using standard system fonts like Times Roman and Arial, you may be safe for both online and printed documents.
But if you are using any non-standard or fancy fonts, you will need to clear in advance that they will be reproduced as intended.
You need to know in advance, for example, if you’d need to package every font you’ve used with the final source files or not.
Help Files
Help files can also become a source of headache when you again assume things.
What format should a help file have? Microsoft CHM, web help, or some other help format?
In addition, are you expected to upload the file yourself or is there going to be someone (usually a developer) who is going to take custody of the file and take care of the rest?
This is yet another set of questions that you must ask before you even start to write the help file and make sure there will be no surprises at the end.
Printing
Printing a document opens yet another can of worms.
Printers are rather fussy about many document variables including fonts, colors, folding, bleeds, binding, etc.
I’d highly recommend you to get in touch with your printer and clear every question before sending over your source files.
A Comprehensive Checklist
There are dozens of such questions in every phase of a writing project.
The bad news is, it’s not easy to remember all of them. We are all human. If you only rely on your memory, omissions, disappointments, and mishaps are unavoidable.
But here is the good news:
I’ve prepared a special checklist of over 60 questions, formatted in easy-to-read tables. If you’d like to get this unique comprehensive list, feel free to click this link: “Questions to Ask Before and After Writing a Document.”
I also have a second offer for my readers: a free report on “7 Great Reasons to Become a Technical Writer.” Click here to download it today.
Write tight. Stay bright. Serve right.
