Facile pen, subject knowledge, and ability to transform technical subtleties into clarities for the end-users - these are must-have talents for a technical writer. Indeed, there’s more to it - we have already written about the skills of a good tech writer. Today we’ll focus on how technical writers start a new documentation project, what they do for starters, how they gather information, and which tools they use.
Any new product is taking shape from the conception and planning stage, then progressing to the product development stage and finally reaching the product delivery stage. In the same way, when technical writers start a project, they go through the following three steps: collect, record, and publish. In this article, we would like to elaborate on the research mastery when creating technical documentation for a product.
Expected Audience: Aim Wisely
A technical writer’s primary job is to document new procedures or product features. At this stage, a technical writer should identify the potential document users and various documentation requirements of the product or feature.
In order to write for the intended audience, tech writers should put themselves in the place of target readers, see the problems they may face, and show them how to efficiently solve the issues with the product.
Technical writers should avoid getting stuck in introductory information they had to learn themselves and instead concentrate on things specific to the company’s tool, which might be immediately useful to users. Conversely, when writing documentation for the average user, it is easy for the technical writer to get too technical or too detailed. Part of the art of technical documentation is knowing the right amount of detail to convey depending on the user. A good tech writer uses featured snippets to solve the issue. Their central aim is to directly answer the user's query in a clear and concise manner with a piece of text extracted from an article on that subject.
A tech writer must determine what the readers are looking for when they begin to read the document and what they'll get out of it.
That’s when data analysis tools come in handy, such as Google Analytics, MOZ, or Zotero.
Architecture: Build Your Document
Bearing in mind who the users are, the tech writer can then conceptualize and plan out the document. Good information architecture is a key supplement to the main product architecture. Well-structured content can be used wherever required in any context. However, technical writers may not have the macro level product vision to handle this stage. Still, let’s enlarge upon that subject to understand the purpose.
To visualize the design of a system, a standard modeling language (SML) or unified modeling language (UML) is used. It helps developers specify, visualize, and construct. The core essence of data modeling — plotting and illustrating the relationship between various entities. The documentation done in the process helps the technical writer greatly conduct technical communication. Naturally, tools used in this phase are more design/modeling tools than technical writing software tools.
These are called data modeling tools, such as Draw.io, Lucidchart, MySQL Workbench, and the like.
Elicitation: Consult SMEs
After a tech writer has the concept, he/she should collect information for new documentation. The first thing to do is ask questions—and that means extracting information from one or more subject matter experts (SME) through an interview. Interviewing SMEs is not that simple; it takes preparation and technique. It’s a soft skill that can pay big dividends well beyond the immediate technical communication project.
STC Fellow Rich Maggiani noted that “Interviewing is research as a social act.”
Every technical writer knows that when preparing to interview an SME, you must do your homework, i.e., doing the background research. Search out existing technical, promotional, and informational documents to provide an overview of the product or service. Start with the company intranet, network directories, and even bookshelves that might contain hard copy information, and expand your search to the internet to get publicly available information.
All notes and data gained should be recorded somewhere. That’s when you use such tools as MS Word, NotePad, Google Docs. It is better to summarize all the relevant information in a flowchart.
What’s Next?
After all the preparation phases, the writing begins, along with reviewing, editing, and publishing. All these are better to perform in a help authoring tool. ClickHelp fits here perfectly. It’s a browser-based documentation tool to create online user manuals, knowledge bases, help files, and publish them in a portal. With so many features at your fingertips, ClickHelp can make your work process better.
Other tools that might be useful for working with content are:
- Clip2net, ShareX, Lightshot for taking screenshots;
- Defect tracking systems like Jira, Mantis, Redmine - to track labor contribution for a project and tasks to perform;
- Camtasia for videos;
- Grammarly for spell checking;
- etc.
The extended list of tools for a technical writer plus more detailed information on how to write a user manual are the requisites for creating well-arranged content.
Conclusion
The toolkit of a technical writer is diverse and manifold. Producing effective technical communication content requires that you’re ready to seek out the experts, ask the relevant questions, and shape the answers into content that your audience wishes to consume. Interviewing SMEs is a technique for extracting essential information that comes with practice.
An excellent technical style is a great way to avoid a situation where the reader begins to wonder how competent the author is on the subject at hand. And remember: if you think loud and clear, your writing is crisp.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices