Turning Documentation into a Product: Best Practices for Success
Tags: webdev, javascript, beginners, podcast
Published: 2024-07-17 02:36:59


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

{% youtube https://youtu.be/5XP0uwMFP20 %}

## 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://www.gitbook.com/)

[https://docusaurus.io/](https://docusaurus.io/)

[https://starlight.astro.build/](https://starlight.astro.build/)

[https://vuepress.vuejs.org/](https://vuepress.vuejs.org/)