Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The PostgreSQL documentation and the limitations of community

rhaas.blogspot.com

Post reply on HN
Print view View original

31–40 of 61 posts

Re: The PostgreSQL documentation and the limitations of community

#31

Post by giovannibonetti »

akira2501 wrote: post #29
pgaddict wrote: post #2

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),…

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 overa…

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/

Re: The PostgreSQL documentation and the limitations of community

#33

Post by Rapzid »

pgaddict wrote: post #2

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),…

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

Re: The PostgreSQL documentation and the limitations of community

#34

Post by actuallyalys »

kaycebasques wrote: post #7

Here'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…

As someone who’s been both a software developer and a technical writer, I agree that a lot of these problems seem best suited for a technical writer. The expertise with creating different types of documents is valuable, of course, but there’s another benefit: The organization committing resources in the form of making it someone’s entire responsibility.

While I think updating reference documents lends itself to subject matter experts (especially in a project where this approach is already successful), I think structuring them can be separated and given to a technical writer with more technical expertise or a developer with more documentation expertise.

Re: The PostgreSQL documentation and the limitations of community

#37

Post by tetha »

kaycebasques wrote: post #7

Here'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…

We're seeing similar things at work as the postgres documentation has.

We in infra-ops can give you more details about how our database clusters are designed for resilience, security, safety than you want on more levels than most people in the company know exist. We also have reasoning for all of this available. This is really good to have for customer question sets during sales.

However, this doesn't tell a developer how to connect his spring boot thingy to it, and how to connect and manage his service well. In fact, 80 - 90% or more of the things we know about our database are not relevant to a simple small-scale application running queries on it. And quite a lot of the issues you can have with running your application on a rock-solid database are entirely not relevant at a DBA level. Like, the database doesn't care if your DDL modification is backwards compatible.

And that's something we're currently learning together with a foundation team at work. They are documenting on how to use it well from their side, we're learning about easy mistakes to make and document those, and help with the actionable documentation. And in hard cases we kinda have to talk what's the plan, because it's usually not smart from a DBAs perspective.

Re: The PostgreSQL documentation and the limitations of community

#38

Post by kaycebasques »

akira2501 wrote: post #29
pgaddict wrote: post #2

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),…

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 overa…

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.

Re: The PostgreSQL documentation and the limitations of community

#39

Post by btilly »

minorninth wrote: post #21
btilly wrote: post #12

Earlier quoted context omitted.

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

PostgreSQL, like many other open-source projects, has sponsors and accepts donations. Here's their sponsors page: https://www.postgresql.org/about/sponsors/ Also, I think it's important to note that a lot of contributors aren't volunteering their "free time", they're being paid by some other employer to contribute to PostgreSQL as part of their job: https://www.enterprisedb.com/blog/importance-of-giving-back-...

If you read https://www.postgresql.org/about/policies/sponsorship/ you'll find that the list of sponsors is essentially a recognition for companies paying their employees to contribute to PostgreSQL.

It isn't for contributing into a pot of money allowing some central PostgreSQL committee to hand out money for other things, like hiring people to do documentation.

Re: The PostgreSQL documentation and the limitations of community

#40

Post by akira2501 »

kaycebasques wrote: post #38
akira2501 wrote: post #29

Earlier quoted context omitted.

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 overa…

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.

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

Post reply on HN