What is the automatic manual?
Is it a new type of machine operating mode or perhaps just another term for semi-automatic? Is it a hybrid vehicle transmission? An oxymoron? Is it like the oft-uttered speech contradiction “yeah no” (or perhaps the “no yeah”)?
Could it be the latest and greatest documentation-writing software available to technical writers (or authors, if you prefer) that automates the entire manual writing process so there is little more to do than click the mouse a few times then kick back the rest of the day and watch You Tube videos?
Well… not exactly.
While there are numerous software tools available to help technical writers present information in different formats and media devices, the basic task of manual development is still very much, well, a manual function.
What does it do? The writer needs to have a general understanding of what the deliverable product – machines in our case – is, then it has to be determined what the product does and how it does it.
Know your audience. With just about any document provided to a user, it’s important to understand the target audience – or audiences – which will dictate the level of detail required. Typical target audiences include, but are not limited to:
- Operators – Require detailed understanding of machine operation and safety features with a general knowledge of the machine function and basic troubleshooting.
- Maintenance Technicians – Require a greater understanding of the machine function and equipment, safety features, general machine operation, maintenance tasks and procedures and detailed troubleshooting.
- Engineering – Require a high level understanding of the machine function (including theory of operation) and equipment, safety features, machine operation, overview of maintenance tasks, calibration and detailed troubleshooting.
R&G time. A major part of developing the manual is researching and gathering all the information to satisfy the content requirements, such as safety, operation, maintenance, etc. This information can be found in varying degrees from numerous sources which may include:
- Customer statement of work (SOW) document
- The machine sales proposal
- Engineering drawings (electrical, HPL and mechanical)
- Project team members (project manager, engineers and builders)
- Tier II/purchased equipment documentation
- Past similar or related machine manuals
In many ways, obtaining technical information can be kind of like a Goldilocks and the Three Bears scenario. Sometimes, there may be so much information (papa bear) that it can become overwhelming just trying to figure out what is valuable and should be included – and equally, what should be excluded.
Other times there is not enough information (mama bear) which creates many gaps and leaves lots of questions that need to be addressed in order to complete the manual.
On rare occasions, there is just the right amount of information (guess who – but not the band) that satisfies all or most of the content requirements.
Get organized. All the information that’s been obtained must be organized into logical categories (or sections) and in a logical flow within those sections. Again, customer specifications may dictate what those sections are and what the minimal content of each section should be (that makes it semi-automatic) but the writer still must take all the bits of information and make it logically fit those requirements.
A picture is worth many words. Let’s not forget about the illustrations needed to support the written text, including photos, 2D line drawings, 3D engineering model images, internet image captures and those created from scratch in a graphics program.
A closer look. After the manual sections are developed they must be reviewed. Beyond performing spelling and grammar checks (again, semi-automatic processes typically found in the word processing or publishing software), each manual section, as well as any supplemental documents, should undergo the following:
- Internal technical review by the engineering team or other project SMEs.
- Validation of procedural content. Ideally, this is performed at the machine, going through the documented process by someone who is not familiar with the machine or the associated documentation. Perhaps this person (the validator) has some technical background or skill related to the tasks covered in the documentation but otherwise remains an objective, fresh set of eyes.
- Customer preliminary review. This is when the customer checks the submitted documentation against their specifications to ensure it meets the requirements.
- Final reviews. These are performed internally by the project team and then by the customer to ensure all updates, changes and corrections driven by the aforementioned reviews have been incorporated and that the documentation accurately reflects the as-shipped machine.
Last but not least. Finally, it is time to deliver the completed manual(s), along with the rest of the technical documentation package (drawings, Tier II literature, etc.) required in the customer SOW. The specified deliverable format can include hard copies, electronic media, uploads to a customer FTP (file transfer protocol) site or any combination thereof.
So, whether you are a long-time technical writer or new to the profession, whether you’re documenting a very “simple” machine or a large assembly system, whether you are developing only a brief overview or a deep dive, the basic function of technical documentation remains unchanged after all this time.
The takeaway here is that an automatic manual does not exist. We don’t have an ‘AUTOMATIC’ button to significantly reduce the work. Of course, if such a button did exist, someone would have to manually document its function.
