5 ms·

I 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 pr

I 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 ago
This 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 ago
Another 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.
- starkparker 3y ago
  > 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. Tutorials and best practices come about from real-world usage, which is why they're often out of date — by the time someone becomes enough of an expert on features specific to a version to write good-quality content of that nature, a new version is out. The only way to update those is through real-world usage, which means shipping pre-release versions for long-enough periods of time and having them used to ship real things, all before the release. Does PostgreSQL do this? It hasn't in my experience, but it's admittedly limited to the last 5-6 years.
- friendzis 3y ago
  > 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 tend to see this as duality of static/ephemeral. On one hand you have "vendors" treating software as rolling moving target - latest and greatest is all there is. On the other hand, there are community guides and tutorials that are out there and never retracted or amended. Let's say I find an article that luckily states being written against older version of software. How do I know whether the information is still valid and applicable to a newer version? Well, if I am lucky and the vendor publishes growing changelog I have to read it and judge of the changes are applicable. Maybe I have to hunt down changelogs from all the interim versions just to see if anything important to me changed. Most probably I will find a very succinct summary of the change like "toll x was merged into tool y" or "updated interface of x". Now I have to try and find the discussion around the change in mailing lists (hopefully the team has not migrated to Discord). Contrast this with hardware. Quite possibly I will find erratas and/or product change notices discussing the changes, maybe even application guides discussing how to apply changes. Unless there is an entirely new product line being released there is high change there will be rather detailed documentation on changes. Software is usually majorly lacking in this regard. And no, versioned documentation is not the answer. Documentation gets updated not only technically, but also as discussed structurally. Once a piece of documentation gets moved to another section or even reworded I can no longer reasonably search for changes. Documentation of a changing, evolving thing is hard and interestingly this is where open source gets hit the most - there are almost no incentives for someone to write good documentation.
derefr 3y ago
These concerns seem to be specific to cases where there are various competing high-level design "strategies" with political weight behind them. There are cases where PG is missing high-level docs where I don't think this applies. For example, there's no official doc on how to write PL/pgSQL code. There's just an extremely-low-level language reference, covering each syntax element separately. There's no cookbook (other than the few examples per syntax element that exist to document the edge-cases of use of that syntax element); no tutorial; no efficiency/performance/scalability guide discussing when certain language features should be favored over others given the current way they're executed (e.g. is IF-ELSE, CASE-WHEN, or a series of IFs with early returns cheaper? when should I favor using FOR with a query, vs. when should I query data into an in-memory array variable and then use FOREACH, vs. when should I query data into a TEMPORARY table and then query that?); no place where you can get a sense for how procedure CALLs interact with MVCC (e.g. when they acquire + release locks, and therefore how and when they cause blocking on contended tables vs. how and when a SELECTed function that uses dblink/fdw to run independent txs would do so); etc. There isn't even a single mention of which PL/pgSQL exceptions are potentially raised by what PG builtin functions when called in a PL/pgSQL context; how to name those exceptions to match on them to catch them; or how to raise them yourself. I often need to dig into the PG source code to figure that out! (PL/pgSQL honestly feels, in docs terms, like a proprietary third-party language-engine "plugin" that someone bolted on, where the docs were expected to be provided by the third party, but never were. But it's not! It's a first-party language, and the reference implementation of how to create a language extension!)
akira2501 3y ago
I really miss old-school printed documentation's "Theory of Operation" section. To me it's the most useful way to bridge this gap. The technical and operations manual describe all the parts and how they function, but the theory of operation really laid out how and _why_ all of these things were structured the way they were. It also forced the designers to think in those terms and to document the product from an overall perspective rather than a component perspective. It was high level enough to be useful, but not so high level as to be abstracted into hand holding tutorial exercises. I feel like most modern software documentation entirely misses this component and would benefit greatly from having it.
- giovannibonetti 3y ago
  Related: Diátaxis - A systematic framework for technical documentation authoring [1] "The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product. Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.(...)" [1] https://diataxis.fr/ https://diataxis.fr/
- kaycebasques 3y ago
  Can you link me to a good old school "theory of operation" section? I get the idea but I want to see firsthand what you mean.
  - akira2501 3y ago
    The older Harris Corporation AM and FM transmitter manuals was what came to mind when I wrote that. As equipment got modernized, there was less for the operator to know, so they get shorter and shorter over time. Look at the SX-1 AM manual under "Principles of Operation" to something like the HT-35 FM manual under the same. Also.. early computer manufacturers like MITS had manuals in a similar vein for their Altair 8800 box but you can find many examples in this space, there's a stub of a Wikipedia page just for it: https://en.wikipedia.org/wiki/Theory_of_operation https://en.wikipedia.org/wiki/Theory_of_operation
Rapzid 3y ago
> I 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 I honestly prefer this type of documentation. ASP.NET Core has the complete opposite problem where it's too example based.
- F-W-M 3y ago
  For many things it's simple enough to read the code, did this e.g. for the Configuration system in ASP.NET Core. Dunno, if I could do this with postgres.
  - Rapzid 3y ago
    Yeah you'll end up reading the source code regardless if it's simple or not though haha. I've had to read through tons of the Identity and Auth code to get a handle on how to integrate with it and there are TONS of interfaces, implementations, and etc you have to cross-reference and hunt down to start building a mental model. You don't even get a diagram in the docs explaining how all the different filters and crap tie together(on top of auth having ITS OWN MIDDLEWARE PIPELINE) lol. Combine that with maybe the info you are looking for actually is in the docs, but it's sprinkled across loads of examples so it's hard to find or build a comprehensive understanding of.
starkparker 3y ago
From the post: > But, you know, I was a loyal servant of the community process. I was asked to document that stuff, and I did, and I put it in the documentation in the place where it most logically seemed to go. The fact that the overall structure of the documentation probably isn't for the best is not my fault, nor is correcting it my responsibility. And it's not anyone else's responsibility, either. ... > It's not difficult to understand why this happens. If I add a new feature to do a certain thing to PostgreSQL, I am the expert on that feature. There's nobody else who knows better than I do what the documentation for that feature ought to say. My work might have shortcomings just like anyone else's, but especially if I'm just adding new entries to tables that already contain dozens or hundreds of existing entries, how much difference of opinion can there reasonably be? It's more likely that reading the documentation will cause someone to take issue with the design of the feature itself than it is that they won't like the way it's documented. Which, I think, is blind to the bigger issue. As you note: > 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. ... > In other words, our docs are written by devs for devs, and we leave the higher level stuff to tutorials written by others etc. The deeper and more common problem between those two symptoms, which the OP misses, is that the people writing the docs often don't use, and maybe haven't ever used, the tool or features they're documenting in their most common productive modes. The most productive devs are often the least knowledgable people in how most, or even many, users use it. Companies often hire (and compensate) someone to try to take the giant mess of dev-written reference content and make guides out of them. But if those people don't use the product either, you just get better-organized docs that still miss the point. Most tools need usage experts writing docs far more than they need feature or software experts. The time of open-source tools' usage experts — "written by others etc." — is often as or more valuable than the time of the open-source project's engineers'. Usage experts are likely being compensated to do almost anything but document the open-source tool, or might even be compensated to document the tools privately or internally for others in an organization to use them better than potential competitors — the opposite of community. The kinds of tools where this trends toward open tutorial creation and documentation tend to have communities of users who aren't as focused on specific tools or narrow usage as systems tools like PostgreSQL — gamedev and media production tools come to mind. "Make a game" or "make a movie" are no less varied than "make an app" or "make a service", and can still be prone to tooling disputes (ie. using Unity vs. Unreal vs. Godot, Premiere vs. Final Cut vs. Davinci), but seem to fall into the trap of hoarding tool knowledge less often. Maybe because there's more authorship and recognition to those types of work, I'm not sure.
nazka 3y ago
How-to and guides are an amazing way to do docs. I love the guides of Ruby on Rails. I rarely used the API documentation. There is a great article talking about the 4 different types of documentation named the “document system”. https://documentation.divio.com/ https://documentation.divio.com/

friendzis 3y ago

This 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 ago

Another 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.

starkparker 3y ago
> 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. Tutorials and best practices come about from real-world usage, which is why they're often out of date — by the time someone becomes enough of an expert on features specific to a version to write good-quality content of that nature, a new version is out. The only way to update those is through real-world usage, which means shipping pre-release versions for long-enough periods of time and having them used to ship real things, all before the release. Does PostgreSQL do this? It hasn't in my experience, but it's admittedly limited to the last 5-6 years.
friendzis 3y ago
> 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 tend to see this as duality of static/ephemeral. On one hand you have "vendors" treating software as rolling moving target - latest and greatest is all there is. On the other hand, there are community guides and tutorials that are out there and never retracted or amended. Let's say I find an article that luckily states being written against older version of software. How do I know whether the information is still valid and applicable to a newer version? Well, if I am lucky and the vendor publishes growing changelog I have to read it and judge of the changes are applicable. Maybe I have to hunt down changelogs from all the interim versions just to see if anything important to me changed. Most probably I will find a very succinct summary of the change like "toll x was merged into tool y" or "updated interface of x". Now I have to try and find the discussion around the change in mailing lists (hopefully the team has not migrated to Discord). Contrast this with hardware. Quite possibly I will find erratas and/or product change notices discussing the changes, maybe even application guides discussing how to apply changes. Unless there is an entirely new product line being released there is high change there will be rather detailed documentation on changes. Software is usually majorly lacking in this regard. And no, versioned documentation is not the answer. Documentation gets updated not only technically, but also as discussed structurally. Once a piece of documentation gets moved to another section or even reworded I can no longer reasonably search for changes. Documentation of a changing, evolving thing is hard and interestingly this is where open source gets hit the most - there are almost no incentives for someone to write good documentation.

derefr 3y ago

These concerns seem to be specific to cases where there are various competing high-level design "strategies" with political weight behind them. There are cases where PG is missing high-level docs where I don't think this applies. For example, there's no official doc on how to write PL/pgSQL code. There's just an extremely-low-level language reference, covering each syntax element separately. There's no cookbook (other than the few examples per syntax element that exist to document the edge-cases of use of that syntax element); no tutorial; no efficiency/performance/scalability guide discussing when certain language features should be favored over others given the current way they're executed (e.g. is IF-ELSE, CASE-WHEN, or a series of IFs with early returns cheaper? when should I favor using FOR with a query, vs. when should I query data into an in-memory array variable and then use FOREACH, vs. when should I query data into a TEMPORARY table and then query that?); no place where you can get a sense for how procedure CALLs interact with MVCC (e.g. when they acquire + release locks, and therefore how and when they cause blocking on contended tables vs. how and when a SELECTed function that uses dblink/fdw to run independent txs would do so); etc. There isn't even a single mention of which PL/pgSQL exceptions are potentially raised by what PG builtin functions when called in a PL/pgSQL context; how to name those exceptions to match on them to catch them; or how to raise them yourself. I often need to dig into the PG source code to figure that out! (PL/pgSQL honestly feels, in docs terms, like a proprietary third-party language-engine "plugin" that someone bolted on, where the docs were expected to be provided by the third party, but never were. But it's not! It's a first-party language, and the reference implementation of how to create a language extension!)

akira2501 3y ago

I really miss old-school printed documentation's "Theory of Operation" section. To me it's the most useful way to bridge this gap. The technical and operations manual describe all the parts and how they function, but the theory of operation really laid out how and _why_ all of these things were structured the way they were. It also forced the designers to think in those terms and to document the product from an overall perspective rather than a component perspective. It was high level enough to be useful, but not so high level as to be abstracted into hand holding tutorial exercises. I feel like most modern software documentation entirely misses this component and would benefit greatly from having it.

giovannibonetti 3y ago
Related: Diátaxis - A systematic framework for technical documentation authoring [1] "The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product. Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.(...)" [1] https://diataxis.fr/ https://diataxis.fr/
kaycebasques 3y ago
Can you link me to a good old school "theory of operation" section? I get the idea but I want to see firsthand what you mean.
- akira2501 3y ago
  The older Harris Corporation AM and FM transmitter manuals was what came to mind when I wrote that. As equipment got modernized, there was less for the operator to know, so they get shorter and shorter over time. Look at the SX-1 AM manual under "Principles of Operation" to something like the HT-35 FM manual under the same. Also.. early computer manufacturers like MITS had manuals in a similar vein for their Altair 8800 box but you can find many examples in this space, there's a stub of a Wikipedia page just for it: https://en.wikipedia.org/wiki/Theory_of_operation https://en.wikipedia.org/wiki/Theory_of_operation

Rapzid 3y ago

> I 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 I honestly prefer this type of documentation. ASP.NET Core has the complete opposite problem where it's too example based.

F-W-M 3y ago
For many things it's simple enough to read the code, did this e.g. for the Configuration system in ASP.NET Core. Dunno, if I could do this with postgres.
- Rapzid 3y ago
  Yeah you'll end up reading the source code regardless if it's simple or not though haha. I've had to read through tons of the Identity and Auth code to get a handle on how to integrate with it and there are TONS of interfaces, implementations, and etc you have to cross-reference and hunt down to start building a mental model. You don't even get a diagram in the docs explaining how all the different filters and crap tie together(on top of auth having ITS OWN MIDDLEWARE PIPELINE) lol. Combine that with maybe the info you are looking for actually is in the docs, but it's sprinkled across loads of examples so it's hard to find or build a comprehensive understanding of.

starkparker 3y ago

From the post: > But, you know, I was a loyal servant of the community process. I was asked to document that stuff, and I did, and I put it in the documentation in the place where it most logically seemed to go. The fact that the overall structure of the documentation probably isn't for the best is not my fault, nor is correcting it my responsibility. And it's not anyone else's responsibility, either. ... > It's not difficult to understand why this happens. If I add a new feature to do a certain thing to PostgreSQL, I am the expert on that feature. There's nobody else who knows better than I do what the documentation for that feature ought to say. My work might have shortcomings just like anyone else's, but especially if I'm just adding new entries to tables that already contain dozens or hundreds of existing entries, how much difference of opinion can there reasonably be? It's more likely that reading the documentation will cause someone to take issue with the design of the feature itself than it is that they won't like the way it's documented. Which, I think, is blind to the bigger issue. As you note: > 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. ... > In other words, our docs are written by devs for devs, and we leave the higher level stuff to tutorials written by others etc. The deeper and more common problem between those two symptoms, which the OP misses, is that the people writing the docs often don't use, and maybe haven't ever used, the tool or features they're documenting in their most common productive modes. The most productive devs are often the least knowledgable people in how most, or even many, users use it. Companies often hire (and compensate) someone to try to take the giant mess of dev-written reference content and make guides out of them. But if those people don't use the product either, you just get better-organized docs that still miss the point. Most tools need usage experts writing docs far more than they need feature or software experts. The time of open-source tools' usage experts — "written by others etc." — is often as or more valuable than the time of the open-source project's engineers'. Usage experts are likely being compensated to do almost anything but document the open-source tool, or might even be compensated to document the tools privately or internally for others in an organization to use them better than potential competitors — the opposite of community. The kinds of tools where this trends toward open tutorial creation and documentation tend to have communities of users who aren't as focused on specific tools or narrow usage as systems tools like PostgreSQL — gamedev and media production tools come to mind. "Make a game" or "make a movie" are no less varied than "make an app" or "make a service", and can still be prone to tooling disputes (ie. using Unity vs. Unreal vs. Godot, Premiere vs. Final Cut vs. Davinci), but seem to fall into the trap of hoarding tool knowledge less often. Maybe because there's more authorship and recognition to those types of work, I'm not sure.

nazka 3y ago

How-to and guides are an amazing way to do docs. I love the guides of Ruby on Rails. I rarely used the API documentation. There is a great article talking about the 4 different types of documentation named the “document system”. https://documentation.divio.com/ https://documentation.divio.com/