A Guide to the Documentation Process

This document is a blueprint of my technical writing process. As the first or “lone writer” it’s important to have a clear process so that managers and colleagues can understand how to work with me. This was written for working with small teams including developers, product managers, and CX staff. As part of workflows using Linear, JIRA, or a similar tool. It’s meant to showcase a transparent and efficient workflow for managing documentation tasks, from initial bug reports to comprehensive content plans for documenting new features.

It was originally authored in Google Docs, for easily changing to Confluence or similar content systems. The guide helps teams collaborate effectively on content, ensuring that every documentation request is prioritized, planned, and executed with a clear strategy and shared understanding.

Summary

This document outlines my workflow for all documentation-related tasks. While these templates aim to streamline requests, please don’t hesitate to create an issue that doesn’t fit neatly into a category. During triage, I will convert the issue into the appropriate type in Linear.

My goal is to make it as easy as possible for you to submit a request and for me to act on it quickly.

There are two primary workflows I employ:

• An issue based workflow for ad hoc requests. I move issues from the backlog to my to-do list at the start of sprints. These are typically Common Requests, but can include Diátaxis Article Templates.
• A development cycle based workflow. The goal of this workflow is to embed documentation into the planning stages of our development workflows. Typically as soon as wireframes and initial specs are ready for a feature, we can begin this workflow, commencing with a Documentation Plan Request

Issue Based Workflow

Here’s my workflow for handling documentation requests:

1. Issue Creation: A team member creates an issue and assigns me to it. As part of triage, I’ll adapt issues to the categories from the issue types described below (Create Learning, Documentation Bug, etc.)
2. Triage & Prioritization: At regular intervals, I review all new issues from the backlog. I assess whether the issue has all the necessary information and prioritize it within my workflow.
3. Information Check: If an issue has all the required details, I can add it to a sprint. If it’s missing key information, I’ll label it as “details needed” and communicate with you about what is required to get started.
4. Content Review: Before publishing, I’ll create a new issue for a final review from the person who originally requested the content. Once this review is complete, the content is ready for publication.

I regularly review issues with the “details needed” label, but if the information is not provided, they may be returned to the backlog.

New Product or Feature Workflow

For new features, products, or major updates, my process begins with a Documentation Plan Request. This isn’t just a request for content; it’s a request for me to partner with you to develop a comprehensive plan for documentation for a product, feature, or solution.

1. Initial Request: An engineer or product manager creates a Documentation Plan Request issue.
2. Discovery & Strategy Meeting: I schedule a meeting with key stakeholders to understand the feature, audience, and our goals. We’ll determine the best type of documentation needed (e.g., “how-to,” “reference,” etc.).
3. Statement of Work (SoW): I create a detailed plan outlining the documentation scope, timelines, and dependencies. Depending on the nature of the request, I may present the SoW in a follow-up meeting ensuring the project plan meets requirements established in the discovery meeting.
4. Issue Creation & Execution: Once the plan is approved, I’ll close the initial request and create individual issues for each documentation task, including the standard sub-issues for Research, Drafting, Review, and Publication.

Common Requests

A. Bug (Documentation)

Use this request to correct an existing documentation page. This could be a typo, a broken link, a formatting error, or incorrect information. I frequently convert customer feedback from our docs site into this type of issue for minor changes.

Request Information

• Location: Link the documentation page containing the error.
• Description: Describe the issue clearly.
• Impact (Optional): Explain the importance of this issue or how it affects users.

If the description of the issue is unclear, I’ll follow-up before the issue is moved from the backlog to our to-do list.

B. Editing

Use this to request a content edit of a non-published document (e.g., a Google Doc, Figma file, or presentation). Depending on the scope, this may be completed quickly or scheduled for a later cycle.

Request Information

• Location: Link to the document and specify its title.
• Audience: Who is the primary audience for this document?
• Feedback Type: Specify whether you need proofreading (for style, grammar, and spelling) or a content edit (for clarity, structure, and accuracy).
• Description (Optional): Describe the purpose of the document.
• Timeline: Specify a reasonable delivery date.

C. Publish Content

Use this template to request the publication of a piece of content to one of our documentation sites.

Request Information

• Source Document: A link to the Google Doc, Markdown file, or other source.
• Request Details: A brief description of the content.
• Placement: Where should this content be published on the website?

In order for us to publish the document immediately, the source document must be clear, polished, and ready for publication, additionally, the publishing location on the website should be agreed upon with the broader docs strategy. We can discuss these on the issue comment thread.

As part of the publication process, I will make minor edits to ensure the content conforms to our style guide.

D. Retire Content

Use this template to request the removal of a piece of published content. This typically happens when a product or feature is removed. If a feature is being deprecated (approaching its end of life, but not removed), we can collaborate on a documentation plan to update and retire documentation in line with the deprecation plan.

Request Information

• Link: A link to the content you want to be removed.
• Reason: Explain why the content should be removed.

If the request is overly broad (“remove all content on HMAC authentication”) or poorly substantiated, I will follow up with the team member making the request and the product owner, similar to a documentation planning meeting.

E. Content Maintenance

Highlight areas where a body of documentation may be outdated or inaccurate. While a single bug is for a specific error, this is for a broader review of a topic. Depending on the scope, this may be completed quickly or scheduled for a later cycle.

Request Information

• Area: Links or a description of the content that needs to be reviewed.
• Reason for Update: Explain why the content needs to be updated (e.g., product changes, outdated information).
• Priority: Specify the urgency of the review.
• Subject Matter Expert: A team member who can help with a content review for accuracy.

F. Documentation Plan Request

Request the scoping of multiple issues by the technical writer, typically as part of a project or the development of a new feature.

Request Information

• Topic: Include a brief description of the topic(s) that you would like covered.
• Audience: All relevant audiences for the plan, being more specific is helpful. For example, developers, admins, and users are all different customer personas.
• Subject Matter Expert: Any team members that could be useful for reviewing content or questions about the feature or topic.
• References: Link any internal or external resources that could help with planning documentation for this project. This can include Figma wireframes, the Linear project, Notion pages, etc.

Diátaxis Article Templates

This categorization scheme is based on the Diátaxis framework, which helps ensure that documentation meets a specific user need. If you’re not familiar with these categories, please create a Documentation Plan Request instead.

There are four types of articles in Diátaxis, each corresponding to a different user need:

• Reference: Answering “what” questions. (e.g., an API reference or an encyclopedia entry).
• Conceptual: Answering “why” or “how does” questions. (e.g., an article explaining a core theory or architecture).
• How-to: Answering “how to” questions by providing steps to achieve a specific outcome (e.g., steps to assemble furniture).
• Learning: Designed to teach a new skill or topic, often in a tutorial-like format (e.g., a textbook section on a topic).

A. Create a Reference or Conceptual Article

Request the creation or significant update of a reference or conceptual article.

Request Information

• Topic: A clear and concise topic for the article.
• Audience: Specify the target audience.
• Content Outline: Provide a brief outline of the main points.
• Type (Optional): Specify “Conceptual” or “Reference.”
• Related Resources (Optional): Links to existing documentation or resources.

B. Create a How-to

Request a new “How-to” article that provides step-by-step instructions for achieving a specific outcome.

Request Information

• Audience: Specify the target audience (e.g., “beginner developers”).
• Process: Describe the high-level steps involved.
• Outcome(s): Clearly define what the user will be able to achieve.
• Related Resources (Optional): Links to existing documentation or resources.

C. Create Learning Content

Suggest a new course or comprehensive guide as part of our documentation. They’re designed to teach specific skills or knowledge. Unlike a tutorial, they spend more time and effort explaining or teaching concepts that are part of the process to a user.

Request Information

• Audience: A clear audience, whether internal staff categories or external personas.
• Outcomes: Specific skills or concepts that a docs reader should come away with after reading the article.
• Topics: Relevant categories or labels from the docs site that relate to the desired learning outcomes.
• Related Resources (Optional): Links to existing documentation or resources.

If they are missing any of these elements, we may schedule a follow-up meeting before adding the issue to a sprint.

D. Sub-issues for Content Generation

Every content generation request will be broken down into four sub-issues for tracking:

1. Research: Finding sources, testing functionality, and interviewing SMEs.
2. Drafting: Creating the first draft of the article.
3. Review: A review by a designated SME to ensure accuracy.
4. Publication: The final editing and publication of the article.

My Tooling

My primary environment is Windows 11 Professional, but I’m comfortable adapting to other operating systems like macOS or Linux. The tools listed below are a sample of my preferred setup, demonstrating a modern, adaptable technical writing workflow.

Style Guide

I typically adapt to an existing style guide. If one doesn’t exist, I can help establish one based on industry standards like the Microsoft Style Guide or the Google Developers Style Guide. I’m a strong proponent of using linters like Vale to automate style checks and ensure consistency across all documentation.