6 ms·
The PostgreSQL documentation and the limitations of community
- davidatbu 3y agoAs a regular consumer of pg docs, I vehemently agree that they are incredibly detailed, and at the same time, daunting to navigate.
- kaycebasques 3y agoIf their problem is an abundance of information that is hard to navigate, they really should start experimenting with retrieval-augmented generation search experiences [1] like Supabase AI. One of the great promises of LLMs for docs IMO is the ability to synthesize info from many sources to provide more targeted answers. [1] https://technicalwriting.tools/posts/playing-nicely-with-generative-ai/#crash-course https://technicalwriting.tools/posts/playing-nicely-with-gen... (my blog)
- davidatbu 3y agoI haven't read your blog yet, but I'd be lying if the same thought hasn't crossed my mind :)
- emodendroket 3y agoHow real is this problem though? I have no idea how they're organized because I'm usually led to whatever page I wanted to see by Google anyway.
- e12e 3y agoI do find that the third party site: https://www.postgresqltutorial.com/about-us/ https://www.postgresqltutorial.com/about-us/ is a very helpful supplement to the official docs. Unfortunately it's not comprehensive - for example it doesn't appear to cover pgcrypto extension.
- tmaly 3y agoThis is a very valuable post in my opinion. Documentation is so critical to open source as well as to the private sector. It can make the difference in how long it takes you to complete a project at work.
- jrott 3y agoAt this point I believe that documentation is the most important marketing artifact that a project has.
- kaycebasques 3y agoHere's my perspective. I've been a technical writer (TW) for ~10 years. 3 at an IoT startup, 7 at Google. > The strengths of this process are also its weaknesses. A developer is, by definition, someone who spends the majority of their time doing development, which is to say writing code. Updating the documentation becomes a task that must be completed so that the code one has written can get committed so that one can move on to the next project and write some more code. I may be misinterpreting, but I get the sense that the author feels that there is some kind of more optimal way to split up docs duties. IMO there is not. At least, not for reference docs. As the author said, the people implementing the code are in the best position to keep the reference information up-to-date. If I grokked the rest of the article correctly, the author is essentially saying that the engineers have trouble writing and maintaining the other main types of docs [1] --- guides, tutorials, and overviews (explanations). It also sounds like they are having a "too many cooks in the kitchen" problem with pushing through changes to the other docs. I have a simple answer to that: hire some strong technical writers and make it clear to everyone that the TWs are Responsible and Accountable [2] for those docs. Also, make it explicit that the engineers are a Consulted role when it comes to guides / tutorials / overviews. Writing these types of docs is hard, specialized work. As the author said, the engineers have lots of other priorities. Of course, it's a bit self-serving for a TW to say "the solution is to hire TWs" but I get the sense that people don't realize that the easiest way to get good guides / tutorials / overviews is to hire people who have thought long and hard about those specialized tasks. If you want a good database, you don't expect your TWs to do the job. You get a database engineer. If you want good tutorials / guides / overviews, you likewise shouldn't expect your database engineer to do the job. You get TWs. [1] https://diataxis.fr https://diataxis.fr [2] https://en.m.wikipedia.org/wiki/Responsibility_assignment_matrix https://en.m.wikipedia.org/wiki/Responsibility_assignment_ma...
- btilly 3y agoJust curious. Where do you think that an open source project like PostgreSQL gets a budget to hire anyone? Let alone to dictate a new line of authority to the volunteers who are already maintaining it? And don't forget that there are valuable volunteers who are likely to go elsewhere if too many new rules are added that they don't want to live with.
- vincent-manis 3y agoI love the approach of “change the code, write the documentation”; the code author is in a unique position to be able to explain the new behavior of the system. However, most FOSS projects could benefit from a technical writer, who can improve these first drafts to make them more usable. Back in the Stone Age, companies like IBM had vast writing staffs. As a result, you got entire walls full of documentation. For OS/360, you got Concepts And Facilities, that explained what the software did for you; you got reference manuals; and Program Logic Manuals, which explained, in exhaustive/ing detail, how the program worked (with flowcharts!). Arguably, the software I use today is far more complex than OS/360; yet we don't see the same attention to organization and detail in the documentation. I understand the reasons: IBM's dead-tree wall relied on paying tech writers, and that's incompatible with the tiny budgets most FOSS projects suffer. Far too often, I will go to a FOSS site's documentation page and discover a mass of links to pages that explain how to build the program on Itanium, or why this program is better than another one, with no walkthrough of “how to use this program for a typical case”, or even “if you want to do this kind of operation, these are the pages you need to read”. Often, the documentation isn't included in the repo, which lowers my confidence that the documentation and software are updated in step. So I celebrate projects such as PostgreSQL, Emacs, and Arch Linux (for the wiki)—there are many more—where there is a real effort to create good documentation, even when I think that documentation can be improved or reorganized. Let's not allow the perfect to be the enemy of the good.
- kaycebasques 3y agoThe technical writing community refers to this approach as "docs-as-code". Just mentioning that keyword in case anyone wants to research the space further. There is a famous Write The Docs talk on the topic. I think the same author turned that talk into a book. Fabrizio Benedetti did a cool analysis of various common docs-as-code architectures: https://passo.uno/docs-as-code-topologies/ https://passo.uno/docs-as-code-topologies/
- emodendroket 3y agoI suppose I can see that but I 1) rarely use the index since, like most users, I generally find myself looking at the docs after a Web search 2) have generally found psql documentation to be excellent.
- fdr 3y agoI think Haas is basically right, that the structure flows from the community structure, and that it's not clear alterations would be a net win. pgsql-hackers is producing the kind of docs only they can, but many usful kinds of docs they cannot produce (per Haas's theory, e.g. more narrative in nature) are delegated to the relative anarchy of the Internet, in blogs, comment threads, stack exchange, and such. While there should be a lot of hesitancy at the implied assumption that any particular arrangement is at the efficient frontier -- most situations can be improved in most or all dimensions -- an exchanged loss in the kind of documents that pgsql-hackers is suited to producing is hard to replace.
- paulryanrogers 3y agoThe mailing list is very accessible if a bit old school. You can often get answers from core contributors. Overall I think their approach has scaled well enough. And in the past they have come around on things like replication in core. So perhaps the future will bring some more handholding docs to supplement the reference docs.
- mannyv 3y agoThe problem with developers writing documentation is that they generally have too narrow of a view of things. Here's an artificial example: "Added a setting which allows you to change the size of a boba." It doesn't answer any really useful questions, such as: why would you want to change the size of a boba? What is the effect of various sizes of boba? How does that interact with other settings? As a database user, I actually want to know these things. Internally I have a mental model of how all these settings interact with the product, and I use information about the new setting to adjust that model. For psql in particular, the documentation (as people have pointed out) shys away from anything too "opinionated." But what it should do instead of have multiple opinionated examples. Multiple examples allow me to learn about the different tradeoffs and configuration options. It reminds me of the old days, when the psql docs talked about optimization as a "black art", and basically said "it would be impossible to cover everything, so we won't cover anything."
- justinclift 3y agoThis is kind of what the old PostgreSQL "Tech Docs" website was useful for, back in the day (~20 years ago). Here's a random snapshot of it from the Wayback machine: http://web.archive.org/web/20040630081140/http://techdocs.postgresql.org/ http://web.archive.org/web/20040630081140/http://techdocs.po... Much more user-level oriented than the reference stuff.
- smitty1e 3y agoTl;dr: a designated documentation editor would be both a boon and likely a challenge to retain.
- TX81Z 3y agoI just ask GPT all my Postgres questions now. I think some of this will become a moot point over time.
- lovasoa 3y agoI was recently reading the documentation for pgcrypto to implement user authentication in SQLPage: https://www.postgresql.org/docs/current/pgcrypto.html https://www.postgresql.org/docs/current/pgcrypto.html The page contains the documentation of many functions, all of which raise the following error by default when you run them: No function matches the given name and argument types. It turns out you first have to "install" them by running "create extension pgcrypto", which is obvious to someone who already knows postgres modules well, but not to anyone else, and isn't mentioned anywhere on the page!
- timacles 3y agoYou just click `Up` to go a level higher in the documentation and it explains everything. This is just intellectual laziness. Its like complaining your car manual doesn't say you have to open the hood of the car on the same page it explains how to change the wiper fluid.
- lovasoa 3y agoI am not complaining. What I am saying is that the current experience for most users is the following: I want to compute a sha1 hash in postgres. I make a google search, I click the first link. It says I should run `digest('mystring', 'sha1')`. It doesn't work. Whereas it could be the following just by adding one line to the documentation: I click the first link. It says I should run `CREATE EXTENSION pgcrypto` first. Then `digest('mystring', 'sha1')`. It works.
- stigok 3y agoI find the PostgreSQL documentation to be a seriously good read. Something I'd print and take on the holiday with me.
- globular-toast 3y agoIt sounds like someone should write a book about postgres. I'd buy it. But I think it should be a supplement to the current docs, not a replacement.
- e12e 3y agoI assume you're aware that there are many books: https://www.postgresql.org/docs/books/ https://www.postgresql.org/docs/books/
- pgaddict 3y agoI think the main limitation of our docs is that it mostly explains what the pieces do, not how to use them to achieve a particular goal. For example, we have pretty good documentation of all the pieces to do HA, we just don't tell people how to assemble them together. The reason is, I think, that flexibility is a pretty fundamental part of the project. We're great at providing building blocks (and documenting them), but we steer clear of describing a particular way to assemble them together. For example, we might describe a particular HA approach, but then that would be perceived as "recommended / official" way, giving it preference over other (and equally valid) approaches and tooling. These "how to" docs are bound to be way more opinionated, so we just focus on documenting the pieces. In other words, our docs are written by devs for devs, and we leave the higher level stuff to tutorials written by others etc.
- friendzis 3y agoThis reminds me of technical documentation for embedded devices. Usually you get multiple classes of documents: data sheets, application notes, reference designs, user guides, erratas. The problems described come from trying to be everything in one place, but it does not have to be. As I understand you try to be mostly a data sheet, which is probably a net good, because it is the document needed to be maintained, even if hard to navigate. However, there are more document classes that can be produced. Yes, a reference design is inevitably going to be opinionated, whether it is produced by project team or some internet person. A reference design produced by project team at least has a fighting chance at staying somewhat up to date. And one can discuss tradeoffs between different approaches in an application note.
- briffle 3y agoAnother good example is the differences in the documentation for Indexes, vs the https://use-the-index-luke.com/ https://use-the-index-luke.com/ that explains many of the reasons WHY you want to organize it with great examples. A problem I have is so many tutorials, or 'best practices' I find on the internet are for older versions that don't really apply as well in newer versions of postgres. Like searching for logical replication, you find lots of information for pg_logical for older versions of postgres, but many of those parts are now baked into postgres, but with a different syntax, etc. I would love to see a 'tutorials/guide' and 'best practices' part of the documentation that is updated with each new release, that give examples of the most common tasks, and when/why to use them, and when to move to something more advanced. Some really basic stuff like "this is the 3 best ways to handle replication in version 15, and the 2 or 3 most common ways to do backups, or these are the recommended ways to migrate from the previous version either in place, or to a new server, etc.