6 ms·

Whenever there is a version update, I can't help but be grateful for the documentation ethic of Postgres. For the vast majority of my projects I have to wade th

Whenever there is a version update, I can't help but be grateful for the documentation ethic of Postgres. For the vast majority of my projects I have to wade through unaffiliated and incomplete blog tutorials that may or may not be relevant to the version I'm trying to use. With anything related to Postgres, I may read about something on a blog post, but I always know that I can count on the Postgres documentation if I need supplemental information, or sometimes I'll skip the post and go straight to the official docs. The PostgreSQL project, in my mind, sets the standard globally for software documentation. I should add that Postgres was the first database I ever used, and I literally learned pretty much everything I know about Postgres, SQL, as well as Relational and Set Logic from the official docs. And that was with no background in software development and an undergraduate business degree with Excel being my most technologically advanced toolset. That is a documentation success story.

jrapdx3 11y ago
Remarkable similar to my own history with Postgresql, which I started using in ~1998 at the time of their first public release. Postgresql documentation has indeed been the exemplar for all software, open source or not. It's been the SQL textbook I've relied on. With the steady addition of features, it's gotten much more complex, and there will come a time when using just the documentation won't be enough to learn how to use Postgresql to full advantage. With release of 9.5 we might be there now. Perhaps the logical extension of the documentation is some form of coursework to enable users to learn the DB systematically. I haven't looked into it, this might already be offered.
- AlisdairO 11y ago
  (self plug) for coursework on the read-only SQL side, you might want to give http://pgexercises.com http://pgexercises.com a try. I have ambitions to expand it to include arrays and json, but alas haven't found the time so far...
  - Alex3917 11y ago
    This is awesome, thanks for making it!
    - AlisdairO 11y ago
      Cheers, hope it's useful :-)
- deleted 11y ago
  [deleted]
ptman 11y ago
I call that BSD culture
threeseed 11y ago
> PostgreSQL project, in my mind, sets the standard globally for software documentation. Sure if you already understand PostgreSQL. If you don't then it isn't particularly user friendly. It's awkward to navigate, doesn't explain the basics (how to actually install it) and tends to combine information that is more for advanced users on the same page as beginners. Compare you're standard with mine (MongoDB): http://www.postgresql.org/docs/9.5/static/ http://www.postgresql.org/docs/9.5/static/ https://docs.mongodb.org/manual/ https://docs.mongodb.org/manual/
- simoncion 11y ago
  > ...doesn't explain the basics (how to actually install it)... Er, http://www.postgresql.org/download/ http://www.postgresql.org/download/ and/or http://www.postgresql.org/docs/current/static/installation.html http://www.postgresql.org/docs/current/static/installation.h... ? > ...tends to combine information that is more for advanced users on the same page as beginners. There's a tutorial for beginners: http://www.postgresql.org/docs/9.4/static/tutorial.html http://www.postgresql.org/docs/9.4/static/tutorial.html Then there's reference material in the rest of the manual. The tutorial even suggests the order in which you should read the rest of the manual. :)
  - threeseed 11y ago
    The documentation doesn't explain how to install binaries and the download pages don't either. Everything defers responsibility to whatever package manager you're using e.g. "PostgreSQL can also be installed on Mac OS X using Homebrew. Please see the Homewbrew documentation for information on how to install packages". And the documentation only explains installing from source code which I can't imagine most people aren't doing. The point is that every other database explains precisely the recommended approach for how to install it on every platform.
    - jsprogrammer 11y ago
      The first Mac OS X package is the Graphical Installer. [0] It looks like it takes you to a link that lets you download a .dmg file. I assume those are basically one-click installers for Mac OS X programs? [0] http://www.postgresql.org/download/macosx/ http://www.postgresql.org/download/macosx/
sedatk 11y ago
an interesting point about pgsql is that the team wrote the documentation first and coded it after. when it's finished they didn't need to write docs.
cpursley 11y ago
Speaking of great documentation, I've been blown away by the quality of documentation for sequel - a Ruby ORM that has some more advanced features (than ActiveRecord) for working with Postgres: - http://sequel.jeremyevans.net/documentation.html http://sequel.jeremyevans.net/documentation.html - http://sequel.jeremyevans.net/rdoc/files/doc/postgresql_rdoc.html http://sequel.jeremyevans.net/rdoc/files/doc/postgresql_rdoc... - http://github.com/jeremyevans/sequel http://github.com/jeremyevans/sequel

jrapdx3 11y ago

Remarkable similar to my own history with Postgresql, which I started using in ~1998 at the time of their first public release. Postgresql documentation has indeed been the exemplar for all software, open source or not. It's been the SQL textbook I've relied on. With the steady addition of features, it's gotten much more complex, and there will come a time when using just the documentation won't be enough to learn how to use Postgresql to full advantage. With release of 9.5 we might be there now. Perhaps the logical extension of the documentation is some form of coursework to enable users to learn the DB systematically. I haven't looked into it, this might already be offered.

AlisdairO 11y ago
(self plug) for coursework on the read-only SQL side, you might want to give http://pgexercises.com http://pgexercises.com a try. I have ambitions to expand it to include arrays and json, but alas haven't found the time so far...
- Alex3917 11y ago
  This is awesome, thanks for making it!
  - AlisdairO 11y ago
    Cheers, hope it's useful :-)
deleted 11y ago
[deleted]

ptman 11y ago

I call that BSD culture

threeseed 11y ago

> PostgreSQL project, in my mind, sets the standard globally for software documentation. Sure if you already understand PostgreSQL. If you don't then it isn't particularly user friendly. It's awkward to navigate, doesn't explain the basics (how to actually install it) and tends to combine information that is more for advanced users on the same page as beginners. Compare you're standard with mine (MongoDB): http://www.postgresql.org/docs/9.5/static/ http://www.postgresql.org/docs/9.5/static/ https://docs.mongodb.org/manual/ https://docs.mongodb.org/manual/

simoncion 11y ago
> ...doesn't explain the basics (how to actually install it)... Er, http://www.postgresql.org/download/ http://www.postgresql.org/download/ and/or http://www.postgresql.org/docs/current/static/installation.html http://www.postgresql.org/docs/current/static/installation.h... ? > ...tends to combine information that is more for advanced users on the same page as beginners. There's a tutorial for beginners: http://www.postgresql.org/docs/9.4/static/tutorial.html http://www.postgresql.org/docs/9.4/static/tutorial.html Then there's reference material in the rest of the manual. The tutorial even suggests the order in which you should read the rest of the manual. :)
- threeseed 11y ago
  The documentation doesn't explain how to install binaries and the download pages don't either. Everything defers responsibility to whatever package manager you're using e.g. "PostgreSQL can also be installed on Mac OS X using Homebrew. Please see the Homewbrew documentation for information on how to install packages". And the documentation only explains installing from source code which I can't imagine most people aren't doing. The point is that every other database explains precisely the recommended approach for how to install it on every platform.
  - jsprogrammer 11y ago
    The first Mac OS X package is the Graphical Installer. [0] It looks like it takes you to a link that lets you download a .dmg file. I assume those are basically one-click installers for Mac OS X programs? [0] http://www.postgresql.org/download/macosx/ http://www.postgresql.org/download/macosx/

sedatk 11y ago

an interesting point about pgsql is that the team wrote the documentation first and coded it after. when it's finished they didn't need to write docs.

cpursley 11y ago

Speaking of great documentation, I've been blown away by the quality of documentation for sequel - a Ruby ORM that has some more advanced features (than ActiveRecord) for working with Postgres: - http://sequel.jeremyevans.net/documentation.html http://sequel.jeremyevans.net/documentation.html - http://sequel.jeremyevans.net/rdoc/files/doc/postgresql_rdoc.html http://sequel.jeremyevans.net/rdoc/files/doc/postgresql_rdoc... - http://github.com/jeremyevans/sequel http://github.com/jeremyevans/sequel