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

41–50 of 61 posts

Re: The PostgreSQL documentation and the limitations of community

#41

Post by nightpool »

tetha wrote: post #37
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 develope…

How many small/new services do you have, and how many developers / teams do you have? If most of your developers are working on "small-scale applications running queries", aren't you just spending a lot of developer time on repeating the same work over and over again?

Re: The PostgreSQL documentation and the limitations of community

#42

Post by burnished »

nightpool wrote: post #41
tetha wrote: post #37

Earlier quoted context omitted.

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

How many small/new services do you have, and how many developers / teams do you have? If most of your developers are working on "small-scale applications running queries", aren't you just spending a lot of developer time on repeating the same work over and over again?

Reusable components and code generation covers this pretty well.

Re: The PostgreSQL documentation and the limitations of community

#43

Post by burnished »

kaycebasques wrote: post #24
btilly wrote: post #19

Earlier quoted context omitted.

Sorry if any of my comments came off naive or obtuse when it comes to open source dynamics. If you want that apology to be meaningful, you should learn something. When you're talking about a highly successful open source project that has been going for more than 3 decades, it is beyond ludicrous for you to say, "If the project is going to succeed long-term..." It already has succeeded long-term. And you would be bett…

> When you're talking about a highly successful open source project that has been going for more than 3 decades, it is beyond ludicrous for you to say, "If the project is going to succeed long-term..." It already has succeeded long-term. Yes, your reaction here totally makes sense. Feedback acknowledged. > If you want that apology to be meaningful, you should learn something. I have re-read my earlier comments and I…

Hey, I enjoyed your comments and appreciated your experienced view.

And, that person is being overtly hostile - I can only describe their behavior as making shit up in order to justify picking a fight and talking down to you.

I don't think you should take anything they say to heart - flag and move on at this point.

Re: The PostgreSQL documentation and the limitations of community

#44

Post by _sharp »

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…

Our team recently adopted the Diataxis framework, I guess. We followed this guide:

https://documentation.divio.com/

We've been referring to it as the Divio system though, which appears to be the same thing.

Re: The PostgreSQL documentation and the limitations of community

#45

Post by nightpool »

burnished wrote: post #42
nightpool wrote: post #41

Earlier quoted context omitted.

How many small/new services do you have, and how many developers / teams do you have? If most of your developers are working on "small-scale applications running queries", aren't you just spending a lot of developer time on repeating the same work over and over again?

Reusable components and code generation covers this pretty well.

"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" indicates that it does not

Re: The PostgreSQL documentation and the limitations of community

#46

Post by burnished »

nightpool wrote: post #45
burnished wrote: post #42

Earlier quoted context omitted.

Reusable components and code generation covers this pretty well.

"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" indicates that it does not

Oh, pardon me, I was answering that as a question on its own - I should have made that clear.

Re: The PostgreSQL documentation and the limitations of community

#47

Post by paulryanrogers »

fdr wrote: post #15

I 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 the…

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

Re: The PostgreSQL documentation and the limitations of community

#48

Post by e12e »

davidatbu wrote: post #3

As a regular consumer of pg docs, I vehemently agree that they are incredibly detailed, and at the same time, daunting to navigate.

I do find that the third party site:

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.

Re: The PostgreSQL documentation and the limitations of community

#49

Post by e12e »

globular-toast wrote: post #35

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

I assume you're aware that there are many books:

https://www.postgresql.org/docs/books/

Re: The PostgreSQL documentation and the limitations of community

#50

Post by BSEdlMMldESB »

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 need to develop the techniques (and then the tooling) so that the source code is sufficient to reconstruct the documentation.

LLMs are fit for this use. I think they could get trained on assembly language.

further, I think that at this point, the whole x86 spec is as impossible to analyze 'rationally' as any natural language. funny that it was created by dozens upon dozens of engineers in a rigorous and formal way; and the result is now mega complex. but I digress...

my point is to reconsider x86 spec as a 'natural' language which is the common "tongue" between software and PC hardware.

but by this point there's no expectation that a modern intel cpu is implementing the instructions in the way they were first created. it may well be emulating the x86 spec to the best of its capacity (another computer program "written" in 'microcode', a x86 virtual machine); so when thinking about x86 assembly spec as a language, the software computer is talking to the hardware computer; and if they agree the computer works. (so the socket and motherboard's buses can be understood as network devices xP )

finally, if I can come up with this (LLMs trained on assembly) so can any security researcher from any advanced academy or corporation.... meaning security researches NOT using LLMs like this ones I imagined are not doing their jobs correctly.

Post reply on HN