Rethinking API Documentation as Code, Tests & More

About Manny Silva

Manny Silva is the Head of Documentation at Skyflow and the author of the book "Docs as Test". He is widely recognized for his innovative contributions to the field of technical documentation. Manny's career in technical communication is rooted in a lifelong passion for computers and language. He emphasizes the critical importance of drawing insights from related fields like Quality Assurance (QA), engineering, and product management to continually enhance documentation practices.

In this conversation, we discuss:

We delved into groundbreaking approaches to technical documentation:

• Introduction and Background: Manny Silva, shares his journey into technical communication, highlighting the value of cross-functional learning from engineering, QA, and product teams.

• Documentation as a Product ("Docs as Product"): Manny elaborated on the concept of treating documentation as a product itself, akin to how the Splunk team describes it in "The Product is Docs". This involves applying product management principles—such as planning, scoping, and tracking—to documentation efforts, recognizing its crucial role in user experience, especially for developer-facing products like APIs.

• Effective API Documentation: He addressed common challenges in documenting APIs, stressing the necessity of comprehensive coverage including endpoints, operations, required properties, examples, and error codes. Manny also highlighted the importance of workflow guides that show users how to achieve business goals by sequencing API operations, recommending Tom Johnson's blog "I'd Rather Be Writing" as a valuable resource.

• Ownership of Documentation Quality: Manny discussed that while engineers often generate initial API definitions from OpenAPI specifications, the ultimate ownership of documentation quality is an organizational decision. He asserted that a technical communicator must ultimately own the documentation, even if tools like overlays are used to programmatically apply updates to engineer-generated content.

• "Docs as Code" Workflow: A core topic was the "docs as code" workflow, which treats documentation like engineering code, utilizing version control, text editors, and CI/CD pipelines. This approach enables programmatic improvements through tools like "Vale" for style guide enforcement and "markdownlint" for structural correctness, offering immense flexibility and increasing accuracy and speed in software documentation.

• Onboarding New Writers to "Docs as Code": For those new to "docs as code," Manny suggested focusing on a high-level understanding of the tools and becoming comfortable with the editing workflow within existing pipelines. He recommended resources like docslikecode.com for tutorials and noted that this approach lowers the barrier for contributions from other team members like PMs or customer support.

• Getting Started with Documentation Workflow: Manny provided practical advice for teams, emphasizing the importance of choosing tooling that aligns with their comfort and skills. Key steps include deciding where to store content (e.g., dedicated repository or with engineering code), where to edit (e.g., an IDE), reusing existing systems like GitHub or GitLab, and defining the publishing pipeline, including hosting and CI/CD processes.

• "Docs as Tests" for Accuracy: Manny introduced "docs as tests," a strategy borrowed from QA that applies quality assurance to documentation. This involves treating documentation, particularly procedures, as tests for product behavior. He discussed his open-source tool, Doc Detective, which programmatically validates procedures and can automate screenshot updates, proactively identifying documentation issues and ensuring accuracy. He clarified that "docs as tests" functions as an extra layer of end-to-end testing for the product, distinct from traditional QA testing of code.

• Technical Writer Involvement and Automation: Manny advocated for early involvement of technical writers in the feature development process, reviewing product requirements to anticipate documentation needs. He also highlighted that while AI and ML tools can assist with tasks like style guide enforcement and drafting, they should serve as augmentation, not replacements, for human decision-making in critical areas like information architecture or creating deterministic tests.

• Personal Preferences in Documentation Work: Manny shared his personal experiences, expressing a strong dislike for writing readmes and release notes, calling the latter "the bane of my existence". Conversely, he finds great satisfaction in building harmonious systems with tools that enhance both user and author experiences, and in creating high-quality content that genuinely helps users succeed.

Where to find more about Manny Silva

You can connect with Manny Silva on LinkedIn, explore his blog at docsastests.com, or learn more from his book "Docs as Test". Additionally, for those interested in hands-on exploration or contributing to the "docs as tests" community, his open-source toolkit is available at doc-detective.com.

In this episode, we cover:

• Introduction to Manny Silva and Documentation:

• Documentation as a Product:

• Documenting APIs:

• Ownership of Documentation Quality:

• Docs as Code Workflow:

• Onboarding New Writers to Docs as Code:

• Getting Started with Documentation Workflow:

• Docs as Tests for Accuracy:

• Technical Writer Involvement and Automation:

• Personal Preferences in Documentation:

• Further Resources

Referenced:

• "The Product is Docs" (book by the Splunk team)

• Tom Johnson's blog "I'd Rather Be Writing"

• "Vale" (tool for style guide enforcement)

• "markdownlint" (tool for structural correctness)

• docslikecode.com (resource for docs as code tutorials)

• GitHub

• GitLab

• Doc Detective (Manny Silva's open-source tool)

• docsasests.com (Manny Silva's blog)

• "Docs as Test" (Manny Silva's book)

• doc-detective.com (Manny Silva's open-source toolkit)