Skip to main content

Methodology Aspects

This section outlines how I approach technical writing, research, documentation planning, and content reuse.

Where I Fit In​

As a technical writer, I see myself as a focal point in the information flow of the company. Developers and engineers design and maintain specific components of a product at a deep level, whereas technical writers need to understand the functionality of a complete product with all its component parts at a higher level, and may be required to work on multiple products at the same time. This gives the technical writer a unique overview of a system, including capabilities across versions. If you work at a company for a reasonable period, you will gradually become a go-to person.

I like to get to know as many stakeholders as possible within the company for the products I work on:

  • Backend Subject Matter Experts (SMEs) are the developers and engineers who are the authoritative sources for granular technical or operational knowledge. They produce architectural designs, code, technical requirements, and raw data.
  • Product Managers are the owners of the product vision, strategy, and business value. They determine what features get built, why they matter to the market, and how success is measured. They work on product roadmaps, user stories, market research, and release plans. They are the go-to people when I need to understand high-level use cases and user personas.
  • User Interface (UI) Teams are usually split into two groups: Frontend Engineers and UI/UX Designers. Frontend Engineers understand the user workflows, visual components, state management on the frontend, and how user inputs translate into backend actions. The UI/UX Designer maps out the user journey, wireframes, and visual layout. As a technical writer, I aim for the writing style for the customer persona to be consistent between technical documentation and UI microcopy.
  • Sales Engineers work directly with customers and maintain playbooks. Sales Engineers are most likely to understand which functionalities of the product are most important to the customer and can provide deeper insights regarding user personas. You can learn a tremendous amount from a sales engineer.
  • Customer support teams are the first line of defense for customers. They understand the most common issues and questions customers have and can provide valuable insights into improving documentation to reduce support requests.

Task Prioritization​

Technical writers are often asked to work on multiple products and features at the same time. I prioritize my tasks based on the following criteria:

  • Customer Impact: I consult with the PMs to prioritize tasks that have the most significant impact on the customer experience / business value. This includes tasks that address critical issues (escalations), improve usability, or enhance the overall quality of the documentation.
  • Time-sensitivity: I prioritize tasks that have strict deadlines, such as release notes, product updates, or time-sensitive documentation. I work closely with the PMs to ensure that these tasks are completed on time.
  • Writing Team Impact: If I am part of a writing team, I consult with my manager to prioritize tasks based on the team's overall workload and capacity. Based on the impact to the team, I may have to go back to the PM and adjust the plan.

Information Gathering & The "Investigative" Phase​

  • Attending Design Reviews: I request to be present at design reviews led by PMs to understand why the new or updated feature is required and how it fits into the product architecture, dependencies, user interface and persona, and edge use cases. I take notes and ask questions to clarify any ambiguities. This information helps me build a comprehensive understanding of the product and its components. I also use this opportunity to build relationships with the PMs and SMEs.

  • Raw Information Collection: I feed raw information from internal sources, such as engineering design documents, API schemas, PM presentations, meeting transcriptions, and Pull Requests (PRs), etc., into the company's AI/LLM tool to map out system architectures, dependencies, and functional edge cases. Even though I am working in an internal tool, which lowers the probability of hallucinations, I know the AI is not perfect, so I later verify the information with SMEs and developers to ensure accuracy.

  • SME Interview Preparation: I analyze the information I have collected and prepare my interview questions. I want to make the most of brief face-to-face time with busy engineers.

Content Creation & Review Process Phase​

I use AI as a writing assistant and heavy lifter to help me create first drafts of documentation. I provide the AI with a prompt based on the information I have collected, and it generates a draft that I can then fine-tune and edit. I use the draft as a starting point for my interviews with SMEs and PMs, and I ask them to review it for accuracy and completeness. I also use the draft to identify any gaps in my understanding of the product or its components and ask follow-up questions to fill those gaps. Even at this stage, I want to ensure that the code snippets are accurate and that I have understood the abstract concepts and technical details correctly.

If I am updating existing documentation, I also use the draft to identify any areas where the documentation could be improved, such as adding more examples, clarifying instructions, or providing additional context. I then make the necessary changes to the draft based on the feedback I receive from SMEs and PMs.

Whichever tool I use to create the documentation:

  • I make sure that the content is structured and optimized for AI, so that it can be easily consumed by the AI LLM tool that the company uses. This includes using clear and concise language, providing examples and context, and using consistent terminology throughout the documentation. I also make sure that the documentation is well-organized and easy to navigate, so that users can quickly find the information they need.
  • I provide drafts in a format that is easy for SMEs and PMs to review, such as a PDF, Pull Request, or Web-based output. I also provide clear instructions on how to provide feedback, I make sure to follow up with SMEs and PMs to ensure that they have reviewed the documentation and provided feedback in a timely manner.

I will have as many review cycles as necessary to ensure that the documentation is accurate, complete, and easy to understand. I also use the feedback I receive from SMEs and PMs to improve my own understanding of the product and its components, which helps me create better documentation in the future.

In-Time Publishing​

Throughout the documentation process, I aim to publish the documentation in a timely manner, so that it is available to users as soon as possible. This means that I prioritize the most crtical information and ensure that it is published first, while less critical information can be added later. I also make sure that the documentation is updated regularly, so that it remains accurate and relevant over time.