7 ms·

The following isn’t the top reason I recommend Postgres, but is the reason I think least likely to be echoed in a dozen other comments: Postgres has some of th

The following isn’t the top reason I recommend Postgres, but is the reason I think least likely to be echoed in a dozen other comments: Postgres has some of the best documentation of any software product I’ve ever used. If someone wants to learn about SQL or databases, I always have to restrain myself from recommending that they just read the Postgres manual front to back. It’s comprehensive, it’s well written, it’s easy to navigate, and almost every explanation comes with several clear examples. It’s hard to overstate how valuable a property that is for a product as central to your architecture as your primary transactional database.

abacadaba 7y ago
My pet peeve is great software with incomplete documentation. All that hard work put into the code, just give us a quick example of how to actually use it! Especially where there is maybe a super superficial example, but missing examples of how to use the optional yet essential and non-straight forward arguments/features.
- lainga 7y ago
  Oh! I have a much bigger pet peeve for projects which have a fine and moderately-usable examples section, but then decide that's good enough and never document the API because one should just "look at the examples".
Zelphyr 7y ago
Too many Open Source developers discount the value of documentation. I all too often hear, "It's Open Source so the community should step up and write the documentation." To which I counter that the best person/people to at least start the documentation are the ones who build the product as they're the most knowledgeable about it. The community will gladly contribute. I personally believe that great documentation was a big reason for PHP's success in the early days.
- pweezy 7y ago
  > I personally believe that great documentation was a big reason for PHP's success in the early days. I agree. The culture of user-submitted comments with helpful examples and clarifications on each documentation page was a big part of that, too.
- otterley 7y ago
  Same for all of the GNU software distribution, Sun Microsystems’ products, and SGI’s. Even MSDN has had pretty good documentation. I miss the days when I could understand how something worked just by reading the official documentation first. To this day, in my open source projects, I do not accept contributions that lack either documentation updates or test cases.
  - linux2647 7y ago
    > I miss the days when I could understand how something worked just by reading the official documentation first. This is probably why I don’t read much documentation when I’m working with a library, et al. Never thought about it until I read the parent
- thirdsun 7y ago
  Absolutely. Good, detailed, up to date documentation is one of my top priorities when selecting development tools, frameworks and software.
reilly3000 7y ago
Isn’t it like 3500 pages?
- jl6 7y ago
  And every one of them enlightening! I once did exactly as parent suggested and read the thing as a PDF on my phone, more or less sequentially, in downtime that I would otherwise have wasted. My knowledge of SQL and databases improved immensely. To be fair I think I skipped some of the appendix matter relating to niche use cases.
CodinM 7y ago
This. By chance I started reading the manual for Postgres yesterday and it actually filled some holes I had in knowledge. It's amazingly structured and verbose with extremely clear examples. The PG manual is literally a 0-to-hero resource for everything SQL related.
pas 7y ago
Alas I found the docs hard to navigate, things are not hyperlinked that should be, and I think adding more examples would help. Anyway, IMHO MySQL has similar level of documentation.
codegeek 7y ago
This. I especially love their "don't do this" page [0] [0] https://wiki.postgresql.org/wiki/Don't_Do_This https://wiki.postgresql.org/wiki/Don't_Do_This
h1d 7y ago
It may have a good doc but searchability on the internet is still miles behind MySQL and that actually counts more on daily search for answers. Also I sometimes don't know if I should search with psql or pgsql or postgres or postgresql and I tend to type shorter ones but mysql is quite obvious on that.

abacadaba 7y ago

My pet peeve is great software with incomplete documentation. All that hard work put into the code, just give us a quick example of how to actually use it! Especially where there is maybe a super superficial example, but missing examples of how to use the optional yet essential and non-straight forward arguments/features.

lainga 7y ago
Oh! I have a much bigger pet peeve for projects which have a fine and moderately-usable examples section, but then decide that's good enough and never document the API because one should just "look at the examples".

Zelphyr 7y ago

Too many Open Source developers discount the value of documentation. I all too often hear, "It's Open Source so the community should step up and write the documentation." To which I counter that the best person/people to at least start the documentation are the ones who build the product as they're the most knowledgeable about it. The community will gladly contribute. I personally believe that great documentation was a big reason for PHP's success in the early days.

pweezy 7y ago
> I personally believe that great documentation was a big reason for PHP's success in the early days. I agree. The culture of user-submitted comments with helpful examples and clarifications on each documentation page was a big part of that, too.
otterley 7y ago
Same for all of the GNU software distribution, Sun Microsystems’ products, and SGI’s. Even MSDN has had pretty good documentation. I miss the days when I could understand how something worked just by reading the official documentation first. To this day, in my open source projects, I do not accept contributions that lack either documentation updates or test cases.
- linux2647 7y ago
  > I miss the days when I could understand how something worked just by reading the official documentation first. This is probably why I don’t read much documentation when I’m working with a library, et al. Never thought about it until I read the parent
thirdsun 7y ago
Absolutely. Good, detailed, up to date documentation is one of my top priorities when selecting development tools, frameworks and software.

reilly3000 7y ago

Isn’t it like 3500 pages?

jl6 7y ago
And every one of them enlightening! I once did exactly as parent suggested and read the thing as a PDF on my phone, more or less sequentially, in downtime that I would otherwise have wasted. My knowledge of SQL and databases improved immensely. To be fair I think I skipped some of the appendix matter relating to niche use cases.

CodinM 7y ago

This. By chance I started reading the manual for Postgres yesterday and it actually filled some holes I had in knowledge. It's amazingly structured and verbose with extremely clear examples. The PG manual is literally a 0-to-hero resource for everything SQL related.

pas 7y ago

Alas I found the docs hard to navigate, things are not hyperlinked that should be, and I think adding more examples would help. Anyway, IMHO MySQL has similar level of documentation.

codegeek 7y ago

This. I especially love their "don't do this" page [0] [0] https://wiki.postgresql.org/wiki/Don't_Do_This https://wiki.postgresql.org/wiki/Don't_Do_This

h1d 7y ago

It may have a good doc but searchability on the internet is still miles behind MySQL and that actually counts more on daily search for answers. Also I sometimes don't know if I should search with psql or pgsql or postgres or postgresql and I tend to type shorter ones but mysql is quite obvious on that.