PostgreSQL has been maintaining its documentation in DocBook for over twenty years. It's been successful but not without challenges. PostgreSQL is often praised for its excellent documentation, and PostgreSQL is also often criticized for its hard-to-approach documentation.
Maintaining documentation for a project such as PostgreSQL comes with a number of challenges. There are many challenges writing good documentation, but in this talk we'll focus on the tooling. First, the documentation is quite big: In a printable format it is over 2000 pages. This pushes many build tools beyond their limits. And of course we also want documentation builds to finish in a reasonable time. Second, we need tooling longevity and portability. Database server software is long-running software. We still need to be able to patch and rebuild everything many years from now. In the world of writing and publishing tools, there is often a new idea every few years with many dependencies and no long-term track record, which makes it difficult for us to adopt things like that. It took us many years to get just a few graphics into the documentation because the tooling issues were too overwhelming.
DocBook has been good to us, but there have been plenty of struggles along the way, and there are some concerns about the future.
Speakers: Peter Eisentraut