The Big Book of PostgreSQL

November 20, 2014

Documentation is crucial to the success of any software program, particularly open source software (OSS), where new features and functionality are added by many contributors. Like any OSS, PostgreSQL needs to produce accurate, consistent and reliable documentation to guide contributors’ work and reflect the functionality of every new contribution. Documentation also an important source of information for developers, administrators and other end users as they will take actions or base their work on the functionality described in the documentation. Typically, the author of a new feature provides the relevant documentation changes to the project, and that person can be anyone in any role in IT. So it can really come from anywhere.

Postgres documentation is extensive (you can check out the latest 9.4 documentation here). In fact, the U.S. community PDF document is 2,700 pages long. It would be a mighty volume and pretty unwieldy if published as a physical book. The Postgres community is keenly aware that the quality of documentation can make or break an open source project, and thus regularly updates and improves our documentation, a process I’ve appreciated being able to take part in.

Click-Friendly Styling

Years ago, before I started with EnterpriseDB, I’d often see areas that needed corrections or that could use some clarification in the Postgres documentation. I would submit patches, and they’d get committed, and because I’m one of the admins on the PostgreSQL side, I’d often see people posting questions or corrections in the comments section of the documentation. Those questions and corrections needed review and approval by an admin, so I would go through them. I noticed that a lot of the questions were actually pointing out things that needed correcting or better explanations. Since many of those weren’t appropriate to the comments section, I moved them back to the mailing list so that the community could work out how to answer the question.

Since then, I have spent quite a lot of time reviewing Postgres documentation for factual and grammatical errors, adding index entries to make content easier to find and correcting inconsistencies. I’ve changed paragraphs that I didn’t think were clear enough, sometimes adding cross-references to link related sections. This has made the documentation far easier to navigate and it’s easier for used to locate the information they’re seeking. Everything has its place and is cross-referenced, and you usually find what you’re looking for with just a few clicks.

In 2011, with the input of the Postgres community, I redesigned the documentation so that it was more aesthetic to the reader and easier to visually scan pages. This was originally motivated by the fact that paragraphs and example blocks looked almost the same in my browser, and pages would appear to be one continuous flow of text.  So working with the community, I implemented a significant redesign to give the pages a more coherent visual structure and break information into more distinct sections without actually changing the content of the documentation itself.

Fewer ‘Gotchas’ Simplify Documentation

Today, it’s often said in the Postgres community that the documentation for Postgres is very easy to use and useful. It’s not perfect, like all other documentation, there is always more to do. But the job of documenting Postgres is made easier by the fact that Postgres minimizes the amount that requires explaining. The database has very few quirky functionalities or contradictions, it’s mostly consistent and unsurprising, and the documentation is there mostly to support the unsurprising features.

In all software, you get what you might call “gotchas,” which are things that behave differently than one might expect. A good example gotcha that is commonly referenced and gets a lot of new MySQL users comes up when you try to put 30 characters into a 24-character field. You may think it’s properly inserted because MySQL didn't produce an error, but in reality it’s only been truncated. MySQL simply inserted the first 24 characters and got rid of the rest. The Postgres community tries to minimize these “gotchas” with a good design and by sufficiently documenting exactly how it behaves. Also, anyone can report problems with the documentation if it needs further clarity. If someone happens to say, “The documentation says x but I don’t quite understand it because I’m getting y result,” the documentation is then reviewed and updated by community members so that the question becomes unnecessary in future.

The community scrutinizes changes made to the documentation, and almost nothing makes it in without going past several pairs of eyes. If something isn’t up to scratch, or is misleading or inconsistent with the rest of the documentation, or doesn’t properly explain a feature correctly, someone will typically step in and clarify it. The standards are high and the documentation is under constant review. I believe this is what ultimately ensures the long-term quality and success of Postgres documentation.

Thom Brown is a Principal Systems Engineer at EnterpriseDB and an active member of the open source PostgreSQL community. 

Visit EnterpriseDB for more information about using Postgres in the enterprise or contact EDB and to send an inquiry. 

Share this