1. Markdown as the Preferred Format
LLMs and Markdown: Large language models (LLMs) are particularly adept at working with Markdown, as they have been extensively trained on this format. Markdown is not only AI-friendly but also offers a good user experience for human readers, thanks to its simple and readable syntax.
GitHub Flavored Markdown: Specifically, GitHub Flavored Markdown (GFM) is preferred because it allows the use of tables and integrates seamlessly with Git platforms, which are commonly used for collaboration in documentation projects.
Benefits of Plain Text:
- Markdown offers key advantages as a plain text technology
- Portability: Markdown files are easily portable between applications.
- Futureproof: Being vendor-neutral, Markdown avoids the risk of lock-in.
- Version Control: Markdown is ideal for version control, given its text-based nature.
- Lightweight: It is also lightweight to store and share.
2. Documentation as code works really well with Markdown
Documentation as code is great because it leverages the same workflows, tools, and principles that developers already use for writing and maintaining software. By treating documentation like code, it can be versioned, peer-reviewed, and integrated seamlessly with the software development lifecycle. This approach encourages consistent, up-to-date documentation, as changes to code and corresponding updates to documentation can happen together, reducing drift. Additionally, using tools like Markdown, Sphinx, or MkDocs allows developers to write documentation in a simple, text-based format that can be easily tracked with Git. This makes collaboration easier, facilitates automation (e.g., CI/CD for docs), and ensures that the documentation evolves organically alongside the code, thus providing both transparency and traceability for all stakeholders.3. Extending Markdown for Dynamic Content
Your product documentation may require more than just static content. Frameworks and custom tools can extend Markdown’s capabilities with features like variables, snippets, and conditions, enhancing flexibility for more advanced documentation needs.
If your existing documentation system does not use Markdown, you can convert it to Markdown using tools like Pandoc, which supports a wide range of formats and can convert them to Markdown. This is not ideal as you will have an extra step in your flow but since the value is that AI system can use your documentation, it is a good starting point.
4. Writing Tools for Documentation
- Writerside: A promising tool that supports Markdown-based documentation is Writerside from Jetbrains. It offers an open, non-proprietary syntax and supports advanced features such as variables, snippets, and conditional rendering, making it highly versatile and futureproof.
- Notion: Notion lacks a robust documentation generator, as it doesn’t support snippets, variables, or conditional rendering. However, it offers an excellent user experience and a well-designed API.
- Gitbook: Gitbook is a popular documentation platform that supports Markdown, making it easy for teams to create, share, and collaborate on content. It combines an intuitive user interface with powerful features for publishing, which makes it suitable for both technical and non-technical users. Additionally, Gitbook allows for seamless integration with other tools, making it versatile for different documentation workflows.
- Confluence: Confluence is widely used for team collaboration and knowledge management. While it provides powerful integration and customization capabilities, it does not natively support Markdown as a primary format, which can limit its flexibility compared to other Markdown-centric tools. However, its strong integration with other Atlassian products makes it a popular choice for enterprise documentation.
- MD Editor: This is a new tool and is designed to help you write technical documentation in markdown faster. What’s interesting is that it has a built-in AI that can help you write better documentation and they bet on Markdown.
5. Tools to Publish Documentation
Markdown-based docs can be published as-is using popular tools such as:
This ensures that the documentation remains accessible to users in a user-friendly format.
6. Answering your customer's questions with AI
We are entering a world where AI will increasingly handle user questions. Having knowledge stored in Markdown makes it much easier to create AI-driven search systems such as RAGs. Markdown’s structured format ensures that AI tools can efficiently parse, understand, and provide accurate responses to user queries.
Conclusion:
In conclusion, we recommend relying on Markdown for documentation and knowledge management due to its versatility, compatibility with AI, and ease of use. Markdown’s simplicity and structured format make it an ideal choice for both human readers and AI systems, allowing for seamless integration into AI-driven search environments. Additionally, AGO integrates exceptionally well with any system that uses Markdown, providing a flexible and powerful solution for customer care.
