Diana Payton shared insights on their journey into technical writing and strategies for overcoming "blank page syndrome" by utilizing raw material from engineers and conducting interviews. Diana Payton detailed the standard documentation frameworks—concepts, tasks, and reference—and discussed addressing incomplete API specifications by creating basic "skeletons" and backfilling details. The discussion also covered deep product understanding for technical writers, essential features for API and SDK documentation, and managing large documentation projects through audits and standardization. Diana Payton explained structuring and scaling documentation teams by hiring diverse skill sets, embedding writers with product teams, and collaborating with other departments. The conversation concluded with insights on the appropriate level of detail for user-facing documentation, review processes in small organizations, leveraging AI/LLMs in documentation, essential skills for junior technical writers, and Diana Payton's dislikes and joys in technical writing.
About Diana
Diana Payton is a technical writing expert known for her ability to lead and manage technical documentation projects from inception. She works at Hackmamba as Documentation Manager. She integrates her technical knowledge, including cybersecurity and data science skills, into her writing to deliver effective documentation that supports various technical audiences. She shares her expertise through her YouTube channel called Technical Writing Uncensored, offering advice and insights into the field.
Ready to level up your documentation?
In this conversation, we discuss:
Overcoming "Blank Page Syndrome"
When starting a new project, Diana Payton addressed the challenge of "blank page syndrome" by utilizing raw material from engineers, such as product requirements documents, design documents, or demo videos. They also vwjdualxnt the importance of interviewing engineers or product owners to prle s fnnysn ssfzuakuxklsj zt the product's intent, hcujsd audience, and functionality. A key part of their process involves hands-on experimentation with the feature or product on a development server to understand its use thoroughly.
Standard Documentation Frameworks
Diana Payton elaborated on the three main types of documentation: concepts, tasks, and reference. They explained that "concepts" cover the "what" and "why" of a product, "tasks" detail "how to do something," and "reference" provides detailed technical information. Diana Payton also briefly mentioned tutorials as a fourth type that combines aspects of the other three. This framework is universally applicable to both physical products and software documentation.
Addressing Incomplete API Specifications
Diana Payton discussed the challenges of documenting products in fast-moving environments, especially at startups where API specifications might be incomplete or nonexistent. They described a common "tug-of-war" between sales managers pushing for documentation and engineers needing more time to finalize the product. In such scenarios, Diana Payton advised creating a basic "skeleton" of documentation with available information and backfilling details later, emphasizing that mature engineering processes lead to fewer such issues.
Deep Product Understanding for Technical Writers
Diana Payton stressed that technical writers, especially those documenting software and APIs, should act as users of the product. They advised junior writers to "push every button" and "run every API call" to understand pain points and ensure the documentation is effective. Diana Payton highlighted the importance of testing documentation by attempting to complete tasks solely based on the written information, asserting that if they, with insider knowledge, cannot succeed, end-users will have no chance.
Essential Features for API and SDK Documentation
For API documentation, Diana Payton expressed a preference for the open API spec and interactive features that allow users to make calls directly from the documentation. However, they emphasized that clear explanations of parameters, responses, data types, and formats are vital, even more so than specific tools. Regarding SDK documentation, Diana Payton reiterated the focus on "tasks," providing clear instructions on how to use commands and including numerous code examples for developers. They asserted that users consult documentation to achieve a specific goal, so the information must be easy to find, clear, and quick to implement.
Managing Large Documentation Projects
When starting large documentation projects, Diana Payton outlined two main scenarios: beginning with no existing documentation or inheriting a substantial amount of legacy content. For the latter, they recommended a "documentation audit" to assess what exists, identify issues, and determine what needs to be rewritten or reorganized. Diana Payton noted that in many companies, especially startups, technical writers might also need to establish and standardize documentation processes from scratch, collaborating closely with engineers to ensure buy-in and repeatability.
Structuring and Scaling Documentation Teams
Diana Payton suggested building a balanced documentation team by hiring individuals with diverse skill sets that complement each other. They emphasized the benefits of embedding writers with specific product teams to develop deep domain expertise, while also encouraging cross-training to prevent knowledge silos. Diana Payton explained that scaling from a solo writer to a team requires codifying and systematizing processes that might have previously existed only in the sole writer's head. They also highlighted the importance of technical writers collaborating with other teams, such as support, marketing, sales, and solutions engineers, to understand their unique information needs and pain points.
Deciding on the Level of Detail in User-Facing Documentation
Diana Payton used the "sausage analogy" to explain the appropriate level of detail for user-facing documentation: users only need to know how to "prepare and cook the sausage" (use the product), not "how the sausage is made" (internal workings). They explained that the level of detail depends on the user's needs and the product's range of users, from non-technical evaluators to developers. Proper labeling and organization of documentation topics are crucial to help users navigate and find the information relevant to their specific roles and tasks.
Documentation Review Processes in Small Organizations
Diana Payton stated that in an ideal scenario, documentarians are involved early in the design phase to provide feedback on usability and clarity. They outlined two levels of documentation review: content review by subject matter experts (like product owners or engineers) for technical accuracy and completeness, and grammar/presentation review, ideally by another writer or someone interested in writing. Diana Payton acknowledged the difficulty of the latter for solo writers but suggested using linters or LLMs as aids.
Leveraging AI/LLMs in Documentation
Diana Payton discussed the role of Large Language Models (LLMs) in documentation, noting they can generate good rough drafts if provided with sufficient raw material. However, they emphasized the critical need for subject matter experts to review every word generated by an LLM due to its potential to produce confident but incorrect or nonsensical information, especially for new products. Diana Payton suggested that LLMs are more reliable for grammar, tone, and objective comparisons (e.g., API output discrepancies), and can help overcome "blank page syndrome" by suggesting headings. They also advocated for simpler tools like linters and spell checks as foundational steps before resorting to LLMs.
Essential Skills for Junior Technical Writers
Diana Payton advised junior technical writers in the software industry to learn at least one basic coding language, like Python, to better understand code and troubleshoot software. They encouraged writers to be open to new tools and changes in the industry, while recognizing the enduring value of human qualities like curiosity, empathy, and asking critical questions. Diana Payton highlighted that technical writers build connections between teams, fill gaps, and advocate for the user, skills that LLMs cannot replicate. They advised junior writers to lean on their soft skills while embracing evolving technologies.
Dislikes and Joys in Technical Writing
Diana Payton expressed a strong dislike for "surprises" in documentation, which often lead to rushed work and incomplete information. They emphasized the importance of early communication, warning, and raw material from other teams to ensure accurate and timely documentation. Conversely, Diana Payton expressed immense satisfaction in collaborating with subject matter experts and product owners who understand documentation's importance. They loved building a strong documentation culture where teams proactively consider documentation needs, leading to smooth, repeatable processes and the joy of publishing high-quality, useful content for users.
Where to find more about the Guest
You can find Diana on LinkedIn for professional communication about documentation.
He also runs a YouTube channel: Technical Writing Uncensored about various aspects of the craft of technical writing
Share this post