TL;DR: ReadMe can now generate PDFs of documentation projects (here’s an example generated from ReadMe’s Product Guide)
Why Did We Build This? This has been a rather large ask from our clients for a long time! Many of our enterprise customers require this, if they are working with a public/government agency. Most of our inquiries about why led to, "government contracts that require this feature." When we asked, "Why do public entities need this feature?" the answers usually came down to the ability to have product documentation available offline.
We had previously debated whether to build a PDF generation feature because of where it positions us philosophically, between the kind of interactive service we are striving toward and the static nature of PDFs. On one hand, we advocate for more interactivity in documentation with more observability for APIs. On the other, we still serve an industry that sometimes relies heavily on offline documentation.
What Does it Mean to Offer a PDF as Documentation?
If you provide PDF documentation, what does it say about the ability to provide backward compatibility for the services a company provides? Our questions led us to the idea that companies have an implied understanding that a service will continue to operate in the way outlined by the PDF. This is often the case at government agencies and other organizations with strict documentation requirements.
To paraphrase one ReadMe customer: "It is important our docs are available at all times to our users. So, we need the ability to export content to PDF and to make sure the content is always up to date with what is online."
When you generate a PDF in our platform, we'll pull in the latest content from your official version in ReadMe. This means that even if you have the same version, you may see that there is a difference between the two PDFs.
To follow best practices and avoid confusing scenarios like the one above when generating PDFs, we strongly recommend following proper versioning guidelines. If you have a small typo or minor edit that you need to fix, that is reasonable to do so within the same version. But if you have an update or addition to the content, create a new version to mark the change.
What Kinds of Rad Things Can You Do Using ReadMe With This New PDF Feature?
- You can write your docs as code, and generate PDFs (which documentarians will love)!
- You can maintain multiple versions of your docs as PDFs!
- You can write markdown and build a PDF from it that actually looks pretty!
In Conclusion
Our PDF feature is new and ready to go! We are already working on improvements for a more beautiful table of contents, better markdown processing, and eventually language translation capabilities. If you are working in an industry where offline documentation is a baseline requirement, our PDF generator is an essential new feature for you!