In part 1 of our blog series on creating effective technical documentation, we discussed the different types of users that technical documentation supports, along with the ways in which good technical writing can benefit your business as a whole:
- Reduced training time and costs
- Enhanced operational efficiency
- Improved outsourcing
- Increased company value
- Improved regulatory compliance
- Increased sales
- More efficient system upgrades and troubleshooting
In order to capitalize on these benefits, it is often helpful for organizations to undergo a bit of a shift in the way they view technical documentation. All too often, company executives, managers and/or developers see documentation as just a necessary evil – something that needs to get done because customers or regulatory agencies expect it. This can lead to a scenario where engineers and/or developers quickly put together documentation at the end of the project just before product launch.
In today’s highly competitive business environment, documentation neglect is not a winning strategy. Leading organizations have made a paradigm shift in this regard and view technical documentation as a critical project deliverable that is an essential part of good product development. Indeed, even in the digital age, a good user guide for a software application can be a vital part of what makes or breaks successful user adoption.
Like any other project deliverable or product, technical documentation needs to be planned, created, delivered, and managed in a way that intersects the needs of users with the needs of the business. The bottom line: Organizations should follow a best practice approach to ensure their documentation takes care of the people (users) that take care of them.
Best Practices for Creating Effective Technical Documentation
Writing and releasing effective technical documentation requires a best practice methodology to ensure the maximum benefits for your organization. Key steps of this methodology include:
Create a documentation plan. The first step in any documentation project should be to create a plan that serves to align all technical documentation with the needs of the organization. Technical writers will need to interview company stakeholders, including product manager, QA, Legal, and subject matter experts (SMEs), to gather the information necessary to begin the plan. The documentation plan is typically introduced to the team during a kickoff meeting.
A document plan should include the following:
- Purpose – What is the intended purpose of the documentation? What problems will the documents be solving? What will readers of the documentation be using it to accomplish?
- Audience – Who are you writing for? What are the user’s needs? At which point in daily job performance will users likely need the content? These questions should be answered for both current and potential future users. Technical writers will want to know as many relevant details of the intended audience as possible – age, education level, job title(s), job function, learning styles, technical expertise, skills, etc. In gathering information, technical writers will typically want to talk to either actual users or people who are interacting with the company’s userbase (e.g., salespeople, account managers, customer service, etc.).
- List of deliverables – What documents will the team write? What are their IDs according to the repository used to store them? What is the status of each deliverable?
- Team – Who are the team members and their roles? Who will be reviewing and/or approving the documentation? Who are the backups?
- Existing resources – What documentation is currently out there? Will you be starting from scratch or simply merging current resources? Are there old, outdated versions of the documentation that will need to be removed from circulation? Where are the voice-of-the-customer transcripts to define requirements? Technical writers will want to conduct a thorough audit to find out what documentation is currently out there that will either help them write or confuse the audience if they find it.
- Authoring and software tools – What software tools, software, and/or websites will be used to create and manage the documentation? Gone are the days when Microsoft Word was the only tool used for technical documentation. Technical writing today encompasses not just written text, but also demo videos, interactive media, online Wiki pages, and much more. New authoring tools, including content management systems, are replacing traditional authoring tools, making it easier for technical writers to assemble task-oriented topic-based deliverables. It is important for a technical writer to be well-versed in the different tools/software for technical writing that have emerged in order to choose the most appropriate tool(s) for the job.
- Style guides – Does the company have a style guide that details what grammatical styles, fonts, languages to use for technical documentation? Are there specific mandates on how to talk to users? Also, some industries require technical documentation to be written in a specific way (e.g., Simplified Technical English for aerospace, aviation and defense companies).
- Outline – Technical documentation is as much about structure and presentation as it is content. No matter how good the information is, if it is not formatted well it can be difficult to use. As such, effective technical documentation is carefully planned and organized. Technical writers should create a table of contents for each technical document they are writing that lists out the hierarchy of information (i.e., topics and subtopics) that will be presented. The outline should be a simple and logical structure that supports reader comprehension, is consistent across documents, and makes your documents easy to navigate and search.
- Schedule – What are the milestones and deadlines to complete each deliverable? How many review cycles will you schedule for each? The number of review cycles typically range from two to three.
Align on a review schedule. Writing is a cyclical process, and good technical writing requires concepts, processes, and terminology to be clarified and honed over time. Unless the technical writer is an expert in the topic, timely feedback from subject matter experts will be essential as the process proceeds.
A review schedule should be created with key SMEs to help improve the value and accuracy of the document as it is being written. At minimum, SMEs should review and provide feedback on the initial outline for the documentation, at least one draft in progress, and the final draft. The initial review will provide feedback on the broader outline, flow and structure of the document, while the review of an intermediate draft and final draft will provide thorough feedback on the content. Ideally, one SME will serve as the single point-of-contact for a group of SMEs to curate comments before marking up the draft.
In between reviews by SMEs, it can be helpful to have a colleague or project stakeholder review the document to help catch any typos or grammatical issues, check that the links and other navigational elements work, and make sure the concepts discussed are easily understandable. The more feedback is collected from different readers and perspectives, the more accurate and readable the document will become.
Pro tip: Do not hesitate to schedule writing sessions to resolve edits among SMEs. Circulating a PDF and asking for comments on a few remaining issues is most effective towards final completion of a deliverable.
Create a document release protocol. A protocol should be developed for final document approval and release. This should involve the proper company stakeholders and will need to be coordinated with the company’s quality department in regulated industries.
Manage the project. Documentation projects can involve many different stakeholders located around the world for global organizations. There are a lot of moving pieces to a successful documentation project.
- SMEs must be interviewed to gather information and sometimes trained to assist with the writing.
- Documentation needs to be managed properly (e.g., version control, user access, etc.) within the software and/or websites where it is housed as it is developed.
- Effective communication must be facilitated between all parties involved in creating, reviewing, and releasing documentation. This can involve navigating language barriers in multi-site, global organizations. Do not estimate the impact of different time zones on team productivity and impact on tight deadlines.
- The review and document release processes must be coordinated and managed. Under cGxP, release processes must be traceable to review the entire document history.
The best technical writers have the skills to coordinate all these activities and effectively manage the documentation project.
Create an update schedule. The job of a technical writer is not done when a finalized document is released and delivered. Documentation can go out of date very quickly as products, processes and software systems change over time. Technical documentation is living content that needs to be kept up-to-date and current with new product releases, upgrades, and process changes. As such, technical writers should create a schedule for regular review and updates on all documentation they deliver. Under GxP, deliverables are often required to be reviewed on a periodic basis. As part of the review, technical writers can talk to relevant stakeholders within the company (e.g., customer service) to identify common complaints and/or support tickets that can provide insight on how documentation could be improved.
Conclusion
Technical documentation plays an important role in your company’s success by giving people the information they need to perform tasks successfully. Technical documentation should never be viewed as just another task to be completed, but instead as an essential part of supporting the people that support you.
Be sure to check out the next installment in our blog series on strategies for creating effective technical documentation (part 3), where we will discuss a variety of writing tips that will help you create world-class technical content.
