Contrary to common assumptions, the documentation for Postgres Pro products is crafted not by developers, but by a dedicated team of technical writers. This team has seen its size double over the past year, reflecting the growing importance of clear and accessible documentation. As Postgres Pro is a fork of PostgreSQL, the source documentation is initially developed in English before being translated into Russian.
Tools of the Trade
The technical writers utilize a variety of tools to ensure the documentation is comprehensive and user-friendly:
- DocBook XML — The primary markup language inherited from vanilla PostgreSQL, enabling the creation of documentation in multiple formats, including HTML for online access, PDF, and EPUB for offline use.
- Markdown — Employed specifically for the documentation of DBaaS products.
- Weblate — A localization tool that facilitates the translation of both documentation and Postgres Pro messages, including error and warning texts displayed in the console.
- Pandoc — Utilized to convert documentation from Markdown, reStructuredText, and other formats into DocBook XML.
- Figma — An interface design tool used for proofreading UX texts associated with Postgres Pro products featuring a graphical user interface, such as DBaaS and PPEM.
The Documentation Workflow: A Quest
The documentation workflow at Postgres Pro resembles a multi-stage quest, meticulously designed to ensure accuracy and clarity:
- Task Setting: When a new feature is developed, the developer can request documentation. This triggers the automatic creation of a documentation task, which is assigned to the team lead and subsequently to a technical writer.
- Draft Preparation: The assigned technical writer immerses themselves in the topic, reviewing the task, developer correspondence, internal documentation, and even examining the code to grasp the feature’s essence. For particularly complex topics, a demo may be requested from the developer.
- SME Review (Fact-Check): The completed draft is sent to the developer for review. This stage often involves a back-and-forth process of edits and feedback until the developer is satisfied with the outcome.
- Peer Review: Following the developer’s approval, the document undergoes a review by another technical writer, who checks for grammatical accuracy and adherence to the glossary and style guide.
- Commit and Translation: Only after two rounds of reviews is the English version deemed ready for commitment to the development branch. A special script then automatically sends the new texts to Weblate for translation.
- Translation Review and Release: The Russian-translated text is subjected to another peer review to ensure the quality of the translation and the accuracy of terminology. After final edits, the team awaits the release.
Working with PostgreSQL Documentation
In addition to their own product documentation, the team also fully translates the documentation for vanilla PostgreSQL releases. This process goes beyond mere translation; they prepare patches for vanilla PostgreSQL whenever inaccuracies or errors are identified.
This translation process is automated. A script retrieves the original .sgml files from the PostgreSQL repository, converts them to .po (Portable Objects) format using the xml2po utility, and uploads them to Weblate. Once the translation is complete, the files are returned to the repository, where the release team can access them.
Feedback Mechanisms
The team actively gathers feedback from various sources to continuously improve the documentation:
- Internal chat: Colleagues from tech support and consulting are among the most engaged users of the documentation, often the first to report errors or gaps in information.
- A form on the website that allows any user to report issues.
- Personal messages received via email and messaging platforms.
While the team strives to address all feedback, immediate edits are not always feasible due to the release cycle’s close ties to development. However, rest assured that every message is acknowledged and will be considered for the next release.
