There used to be a question haunting me for a long time--How to document instruction guides such as Installation Guide in a topic-based way? I have the perfect concept of task-based writing and know how to well document a single task. But how to group these tasks? Do I need to go back to the linear process stringing these tasks together? (As I mentioned before, we've taken training on task-based writing, and well learned that task-based writing is a non-linear writing method.)
My concern doesn't come out nowhere. It was that I often received complaints from the readers (implementation engineers) --They couldn't set the system up following the guide. After mulling over the concerns for a long time, maybe, one or more years. I took actions to restructure my guide by writing instructions based on an installation example.
Detailed practices are as follows:
- State my assumption at the beginning that this guide is written based on an installation scenario.
- Write tasks and adopt the linear way to piece these tasks together (I use a workflow diagram to illustrate the relationship between tasks, also at the beginning of a task, I will state that the prerequisite task (e.g. task A) before continuing with this task.
- In each task topic, I write the general task steps and give examples based on the scenario given.
I took this way to protect myself or to say to help defend myself when complains make visits. My bottom line was I could ensure that the content is accurate and thorough. Because installation procedures vary based on onsite scenarios, my way was a one that can convince myself and let me feel no guilty.
系列文章
