Who writes Postgres Pro documentation — and what tools they use
Contrary to popular belief, the documentation for all Postgres Pro products is not written by developers, but by a team of technical writers that has doubled in size over the past year. Since Postgres Pro is a fork of PostgreSQL, we develop the source documentation in English and then translate it into Russian.
What we use:
DocBook XML — the main markup language for documentation, which we inherit from vanilla PostgreSQL. DocBook XML allows us to build documentation in various formats: HTML for the website, PDF, and EPUB for offline client access.
Markdown — the documentation language for DBaaS products.
Weblate — a localization tool that helps translate both the documentation and Postgres Pro messages (yes, the error and warning texts you see in the console), as well as the documentation for vanilla PostgreSQL.
Pandoc — converts documentation from Markdown, reStructuredText, and other formats into DocBook XML.
Figma — an interface design tool where we proofread UX texts for Postgres Pro products with a graphical user interface (DBaaS, PPEM).
The documentation workflow is almost a quest
Our workflow is a multi-stage and complex quest.
Task setting. When a task for a new feature is set, the developer can request documentation for it. In this case, a documentation task is automatically created and assigned to the team lead, who then assigns it to one of the technical writers.
Draft preparation. The technical writer delves into the topic: studies the task, developer correspondence, internal documentation, and even looks at the code to thoroughly understand the feature's essence. If the topic is complex, we ask the developer for a demo.
SME review (fact-check). The finished draft is sent to the developer for review. This stage often turns into a cycle: we make edits, send them for review, receive new comments — and this continues until the expert is satisfied with the result.
Peer review. After the developer's approval, the document goes to another technical writer for review. Everything is checked here: from English grammar to compliance with the glossary and style guide.
Commit and translation. Only after two rounds of reviews and approvals is the English version considered ready, and we commit it to the same branch where the development was done. After that, the magic begins: a special script automatically picks up the new texts and sends them to Weblate for translation.
Translation review and release. The Russian-translated text undergoes another peer review, where the quality of the translation and the correctness of the terminology are checked. After the final edits, we wait for the release.
How we work with PostgreSQL documentation
In addition to the documentation for our own products, we fully translate the documentation for vanilla PostgreSQL releases. And it's not just a translation: we prepare patches for vanilla if we find inaccuracies or errors in the documentation.
The process here is also automated. A script takes the original .sgml files from the PostgreSQL repository, converts them to .po (Portable Objects) format using the xml2po utility, and this is what gets uploaded to Weblate. After we finish the translation, the files are returned to our repository by the same path, from where the release team picks them up.
Feedback
We actively collect feedback from a wide variety of sources:
Internal chat: our colleagues (especially from tech support and consulting) are some of the most active users of the documentation, and they are the first to report errors or a lack of information.
A form on the website through which any user can report a problem.
Personal messages via email and messengers.
We try to process absolutely all requests, but we don't make edits immediately, as our release cycle is closely tied to development. Nevertheless, be assured: no message will be lost and will be taken into account in the nearest release.