DEV Community

Cover image for Turning Documentation into a Product: Best Practices for Success
Alex Patterson for CodingCatDev

Posted on • Originally published at codingcat.dev

Turning Documentation into a Product: Best Practices for Success

Original: https://codingcat.dev/podcast/turning-documentation-into-a-product-best-practices-for-success

Introduction and Tech-Related Banter

  • Technical Setup Issues: The video begins with the host experiencing some technical difficulties related to the pre-roll video.
  • Guest Introduction: Vincent, the guest, is introduced. He recently changed jobs and shares some light-hearted banter with the host.

Vincent's Journey into Tech

  • Career Path: Vincent explains his unique journey from aspiring to be an electrical engineer to becoming involved in software development. He cites his initial influence from a Minecraft streamer.
  • Role Transition: He details his transition from electrical engineering to mobile QA, firmware development, product management, and finally technical writing and developer relations.

Challenges in Technical Writing

  • Language Barriers: Vincent discusses the nuances of English as a second language and how it impacts his technical writing.
  • Writing Style: He emphasizes the importance of clear, simple language in technical writing to ensure comprehensibility. Complicated language often makes documentation less accessible.

Importance of Documentation

  • Product Discovery: The discussion includes how crucial it is for documentation to aid in the user journey from discovering the product to effectively using it.
  • Feedback Loop: Vincent shares his practice of testing documentation clarity by walking through it with colleagues or new hires to identify pain points.

Analyzing Documentation Layouts

  • Various Documentation Sites: The host and Vincent review different documentation sites (Cloudinary, Algolia, Appwrite, and Stripe) highlighting strengths and weaknesses.
  • User Experience: They discuss how the organization and presentation of documentation significantly affect user retention and education.

Treating Documentation as a Product

  • Investment in Documentation: Vincent suggests documenting like a product, highlighting the importance of making a business case for comprehensive documentation.
  • User Journey in Docs: He explains that documentation should be tailored to closely follow the user journey, from first-time use to advanced usage scenarios.

Pain Points and Best Practices

  • Design Collaboration: He advises integrating documentation writing within the product design phase to ensure that both documentation and product flow are aligned from the beginning.
  • Measuring Effectiveness: Vincent talks about using analytics to track user engagement with documentation, identifying drop-off points, and iterating based on these insights.

Future of Documentation and AI

  • AI Integration: The conversation veers into the future role of AI in generating and maintaining documentation. Vincent believes that while AI can assist, human-written documentation will always be required for niche, complex use cases.
  • Role Transition: He envisions AI handling more straightforward documentation tasks with technical writers focusing on nuanced, detailed, and unique documentation needs.

Personal Insights and Preferences

  • Preferred Tools: Vincent suggests starting with markdown-based documentation tools like Starlight from Astro for their flexibility and ease of migration.
  • Tips for New Businesses: He recommends keeping documentation simple and generic initially to allow for future adjustments and scalability.

Documentation Tools

https://www.gitbook.com/

https://docusaurus.io/

https://starlight.astro.build/

https://vuepress.vuejs.org/

Top comments (0)