Hacker News Reader

Comment by nbouscal | Hacker News Reader

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.

View on HN

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.

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

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.

> 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

Absolutely. Good, detailed, up to date documentation is one of my top priorities when selecting development tools, frameworks and software.

This. I especially love their "don't do this" page [0]

[0] https://wiki.postgresql.org/wiki/Don't_Do_This

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.

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

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.

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.

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.

Isn’t it like 3500 pages?

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.

Reply on news.ycombinator.com