Lead Writer: Kieran Morgan | Peer Reviewer/s: Felicity Brand | Expert Reviewer/s: Dina Bennett | Managing Editor: Kieran Morgan

This chapter equips you with essential steps to gather the information you’ll need before diving into the creation of technical documents. We introduce the DIKW Pyramid as a conceptual framework to understand the relationships between data, information, knowledge, and wisdom. Furthermore, the chapter provides insights on locating key resources, such as brand guidelines, templates, and style guides. Finally, we offer tips to set the stage for a successful start to any new documentation project.

Who Should Read This
• Aspiring Technical Writers • Beginner Technical Writers • Career Advancers • Cross-Domain Professionals
Table of Contents: Technical Writing Process
Previous: Chapter 8: Artificial Intelligence (AI) for Technical Writers	Next: Chapter 10: Make a Plan
Table of Contents: Project Management for Technical Writers
Previous: Coming soon!	Next: Chapter 4: Make a Plan

1. Introduction

Technical writers are like proverbial crows: we gather and hoard information with such dedication that you’d be forgiven for thinking we’re going to decorate our nests with it. Don’t be alarmed! This is completely normal behavior for technical writers and something we should all be doing—not only at the start of a project, but at every point along the way.

Technical writing is all about synthesizing a focused piece of information—a technical document—from a variety of sources. This process creates knowledge in the minds of users and enables them to carry out tasks they may have previously struggled with.

2. [Theory] DIKW Pyramid

Although most people use the terms “data,” “information,” “knowledge,” and “wisdom” interchangeably, the DIKW Pyramid provides us with more precise language to articulate our craft.

Let’s imagine you’re a technical writer tasked with writing a user guide for a power saw. How would you explain that in terms of the DIKW Pyramid?

By understanding the DIKW Pyramid, you gain a structured language for discussing and refining your craft, ensuring that you not only collect and hoard information like our metaphorical crow, but also use it to create documents that transform data into actionable wisdom.

Note

Is This the DIKW Pyramid You Remember? There are many variations on the DIKW pyramid, and there’s no rule on which one to use. In fact, some of them even add additional layers, such as “content”.1 We’ve synthesized our own DIKW Pyramid, drawing from Andrew Liew and Jennifer Rowley’s excellent definitions.2,3

What Does That Mean?

Data Basic units of information, like words, numbers, or images, that represent aspects of reality. Information Data that has been processed and organized to support decision-making; for example, a document. Remember it as data “in formation.” Knowledge Information that has been internalized by someone, providing the basis for them to act on it. Wisdom The ability of someone to use knowledge, information, and data to make well-informed and ethically sound decisions.

3. [Practice] Collect Information, Data, and Knowledge

It’s common for technical writers, especially freelancers or contractors, to begin a new project with limited clear instructions regarding expected deliverables. Your manager might not even be fully aware of what the required deliverables should look like; they only know documentation will be needed. This situation is normal, so your first task on a new project should be to activate your inner “bird mode.” Start by searching for existing information before diving into writing or planning. There’s often existing content that you can leverage or repurpose to create your own documentation.

If you’re documenting a product (hardware or software):

• Don’t limit your research to purely technical content or experts. Consult both product managers and engineers. They often have high-level documents, such as board presentations or requirements documents for development. These documents will outline nontechnical aspects, such as the problem the product aims to solve, profiles of intended users, wireframes, and visual mock-ups.

If you’re writing procedural documentation:

• Consult the subject matter experts who perform the tasks you’re documenting. These individuals often have their own documentation which was created as memory aids or for other purposes. Even if they don’t have documentation, build relationships with them early on, as you’ll need their expertise later. Be cautious when reviewing any documents they provide; they might be outdated or of questionable quality, which is likely why a technical writer is needed.

Insight

What If There Is No Existing Information? Occasionally, you might find that no relevant information exists. While this is common for process and procedure projects, it’s a red flag for product development projects. How can a product be planned and developed without specifications? If this happens, discuss the situation with your manager and diplomatically explore why existing documentation is lacking. You might also inquire discreetly within the organization to uncover any hidden information. If you discover that no information exists, consider it an opportunity. Teams responsible for creating this information, such as marketers and engineers, may need your technical writing expertise, allowing you to contribute your skills to the project.

3.1. Check for Templates or Style Guides

It’s crucial to check for existing templates, style guides, and brand guidelines before you write. In larger organizations, templates will often be available that you can—or must—use or adapt for your technical documents. There will also often be organization-specific style guides or brand guidelines that provide guidance on how to write in the company style, properly acknowledge company trademarks, and so on.

These in-house style guides differ from general style guides like the Chicago Manual of Style. General style guides contain broadly accepted rules of writing and grammar. They’re designed to be all-purpose or applicable to a particular industry or region. Organization-specific style guides either supplement or overrule elements of these general guides to align the company’s brand voice as consistently as possible when communicating with customers.

Insight

Turn a Lack of Guidance into an Opportunity If your organization doesn’t have style guides or templates for the documents you’ll be writing, don’t despair. This situation can be an opportunity for you to add value by creating them yourself—provided your manager approves. Style guides and templates save time on future projects, ensure consistency, and create a professional look that aligns with the organization’s brand. They’re also an excellent opportunity to enhance your skills, making you more employable in the future. Creating templates and style guides is a senior technical writing skill.

3.2. Secure Access to Hardware and Systems

One task you’ll need to sort out early on is access to the item you’re documenting. Whether it’s hardware or software doesn’t matter; you’ll create more accurate documentation if you can test it against your instructions. Of course, that’s not always practical or feasible, but you should aim for it.

Whether you’re documenting hardware or software, follow one golden rule: submit your request as early as possible. Gaining access to working prototypes or software environments where you can experiment without breaking anything can take time.

If you’re documenting processes:

• Processes often involve some element of human interaction with software, hardware, or both. You may not always need access to these systems, but you will need access to subject matter experts to validate your documents.
• If they’ve agreed to demonstrate a procedure, request in advance that you can take frequent screenshots from their screens as they proceed. Ask for their patience if you need to slow them down to capture everything thoroughly.

If you’re documenting hardware:

• If possible, get involved early in the product development lifecycle to be integrated into any usability testing conducted by the design team.
• Ask the engineering team for access to a working prototype to test against your documentation. This is crucial for ensuring your documentation is accurate.
• If your hardware interfaces with software, also secure access to that software, including if possible any testing and diagnostic software used to troubleshoot the device.

Tip

What If There’s No Working Prototype? Sometimes there may not be prototypes available, or they might not be accessible within the limited time you have to document them. In such cases, work closely with engineers to understand your alternatives, such as virtual simulations or CAD drawings.

If you’re documenting software:

• Request software access as early as possible. You’ll need it to understand how the software works, capture screenshots, and validate workflows. You might also discover bugs and usability issues.
• Consider the permission levels you’ll need. Administrator access will allow you to access all features and create or delete any dummy data needed for testing and documentation. However, the standard user view might differ significantly, so make sure you cover all your bases.
• Ensure the version you access is regularly updated to reflect the user experience accurately. Maintain regular conversations with developers to keep them aware of your activities—just in case they forget to update the environment in which you’re working.

Tip

Make Sure You’re Documenting the Correct Version When documenting a system, ensure you’re working with the correct version. Features and workflows can change dramatically with updates, quickly rendering your documentation obsolete. Maintain regular, proactive conversations with developers to understand if they’ve updated the code base for your documentation environment and when features will be stable enough for documentation.

Most development teams will have several environments they work in:

• Production or “Live” Environment: This is the environment that end-users and customers interact with. As a technical writer, you most likely won’t need access to the production environment.
• Staging or “Sandbox” Environment: This is a close replica of the production environment but separate and isolated from it. Developers use this environment to test code changes.
• Test or User Acceptance Test (UAT) Environment: Like the staging environment, this is a close replica of the production environment but specifically set aside for testing purposes to identify bugs or usability issues in new or updated features.
• Local Environment: You may have the opportunity to install and run the software on your own computer, allowing you to test the software as if you were an end user.

Note

What to Do if Access Is Denied? It’s not uncommon for technical writers to face resistance when requesting access. Various reasons, such as security concerns, can account for this. However, it’s crucial to be both polite and persistent. Here are some steps to consider: • Ensure you’ve used any formal access request procedures so your request is officially on the record. • Request an appropriate access level that minimizes risks, such as exposing sensitive customer information. • Identify a subject matter expert who has access and ask if you can take screenshots or photographs. • If denied access, consider escalating your concerns to your manager, project manager, or even the legal team.

3.3. Check Out Competitors’ Documentation

If competitors publicly share their documentation, don’t hesitate to review it. This can provide valuable inspiration and insights into industry norms for various types of technical content.

Note

Acknowledging Other People’s Work Always be aware of copyright laws. If you intend to repurpose someone else’s content, you should acknowledge it appropriately. For specific guidance, refer to your style guide, which should include details on copyright and acknowledgment practices.

3.4. Check for Standards

In technical writing, adhering to specific standards is sometimes a necessity. Standards, including those established by bodies such as the International Organization for Standardization (ISO), the Institute of Electrical and Electronics Engineers (IEEE), and Aerospace and Defense industries (ASD), provide a framework for content and presentation that aligns with industry norms, best practices, and regulatory requirements. Before taking the plunge and starting to write, it’s best to check whether your documentation is expected to align with a particular standard.

Why Standards Matter

1. Compliance and Quality Assurance: Standards like ISO 9001 for quality management and ASD-STE100 for simplified technical English help to maintain a high level of quality and consistency in technical documentation. Compliance with these standards ensures that the documents meet specific benchmarks set within the industry.
2. Legal and Regulatory Requirements: In certain industries, following specific standards is legally mandated. This is particularly relevant in fields with high safety and regulatory requirements, such as aerospace, healthcare, and engineering.
3. Best Practices and Benchmarks: Standards often embody best practices within an industry. For example, ISO/IEC/IEEE 26515:2011 provides guidelines for developing user documentation in an agile environment, which can be a valuable resource for teams working in agile methodologies.
4. Translation and Localization Standards: ISO 17100:2015 sets comprehensive guidelines for translation services, ensuring quality and consistency in multilingual technical documentation. This standard is pivotal when preparing documents for diverse linguistic audiences. See Part 9: Translate.

What Does That Mean?

ISO 9001 ISO 9001 is the global standard for quality management systems. It’s published by the International Organization for Standardization, a non-governmental organization that develops and publishes international standards across a wide range of industries and sectors. This standard focuses on ensuring companies meet customer needs for their products and services. It also sets out requirements for document control, which we discuss in depth in Chapter 26: Publish.

4. [Template] Resource Checklist for Technical Document Creation

The Resource Checklist for Technical Document Creation helps ensure you’ve gathered everything needed for your documentation project.

1. Covert, A. (2014). How to Make Sense of Any Mess. Abby Covert, p. 21 ↩︎
2. Liew, A. (2007, June). Understanding Data, Information, Knowledge And Their Inter-Relationships. Journal of Knowledge Management Practice, 8(2). ↩︎
3. Rowley, J. (2007). The wisdom hierarchy: representations of the DIKW hierarchy. Journal of Information Science, 33(2), 163-180). ↩︎