4 ms·

Postgres has fantastic documentation, but it still is rather intimidating to the completely new developer. For example, take the following scenario: 1. Go t

by djm_ 11y ago

Postgres has fantastic documentation, but it still is rather intimidating to the completely new developer. For example, take the following scenario: 1. Go to project's website 2. Click docs/documentation. This is what you get: Postgres: http://www.postgresql.org/docs/ http://www.postgresql.org/docs/ MongoDB: http://docs.mongodb.org/manual/ http://docs.mongodb.org/manual/ RethinkDB: http://rethinkdb.com/docs/ http://rethinkdb.com/docs/ Wipe your entire memory of databases for a second: which one would you chose to delve further into?

anarazel 11y ago
Agreed. I think PG has pretty good reference documentation, with a few weaker sections, but horrible introductory material. Once you're familiar with postgres you wonder why you'd ever need anything more than good reference documentation, but that's just because you now know where to look for what. EDIT: missing word
Gracana 11y ago
Man, the MongoDB documentation looks different. I was getting into it a couple years ago, and I was so frustrated with it, like it would explain that something returns an error but not what the values could be, or the prototype would show it returned something but the documentation wouldn't say what, or parameters would be left unexplained, etc. Looks like it's all new and different now, which is probably a good thing.
anc84 11y ago
Actual link to docs is http://www.postgresql.org/docs/9.4/interactive/index.html http://www.postgresql.org/docs/9.4/interactive/index.html , come on, be fair.
- shawn-furyan 11y ago
  The GP is being fair. The link provided is the one exposed on the postgresql.org homepage. The GP was explicit in considering the different projects from the POV of a new user unfamiliar with them. If the url that you provide is the most appropriate, then that is the url that should be anchored to the 'Documentation' link on the Postgres homepage. I imagine that rethink and Mongo also have point versions. They both choose not to force new users to choose, devoid of context, which point version is most appropriate (sure you can use heuristics, like highest non-experimental point version, but this heuristic sometimes leads to pitfalls, Python and Perl come to mind). And the http://www.postgresql.org/docs/ http://www.postgresql.org/docs/ landing page is made even less necessary since the 'interactive' documentation already has links at the top to other point versions. Throw in a minimal sidebar and you could kill the landing page without losing any of the functionality. Of course, Postgres has been around longer, and their last major website redesign probably pre-dates the entire existence of the other two websites altogether[1], but that has no bearing on which website is the least intimidating to newcomers. If postgres sees fit to make their website less intimidating to newcomers, then their work is cut out for them. [1] Confirmed via Internet Archive's Wayback Machine. The last postgresql.org redisign was complete by early 2006. Mongo and ReThink websites showed up, in minimal form, in late 2008 and early 2009 respectively.

by djm_ 11y ago

anarazel 11y ago

Agreed. I think PG has pretty good reference documentation, with a few weaker sections, but horrible introductory material. Once you're familiar with postgres you wonder why you'd ever need anything more than good reference documentation, but that's just because you now know where to look for what. EDIT: missing word

Gracana 11y ago

Man, the MongoDB documentation looks different. I was getting into it a couple years ago, and I was so frustrated with it, like it would explain that something returns an error but not what the values could be, or the prototype would show it returned something but the documentation wouldn't say what, or parameters would be left unexplained, etc. Looks like it's all new and different now, which is probably a good thing.

anc84 11y ago

Actual link to docs is http://www.postgresql.org/docs/9.4/interactive/index.html http://www.postgresql.org/docs/9.4/interactive/index.html , come on, be fair.

shawn-furyan 11y ago
The GP is being fair. The link provided is the one exposed on the postgresql.org homepage. The GP was explicit in considering the different projects from the POV of a new user unfamiliar with them. If the url that you provide is the most appropriate, then that is the url that should be anchored to the 'Documentation' link on the Postgres homepage. I imagine that rethink and Mongo also have point versions. They both choose not to force new users to choose, devoid of context, which point version is most appropriate (sure you can use heuristics, like highest non-experimental point version, but this heuristic sometimes leads to pitfalls, Python and Perl come to mind). And the http://www.postgresql.org/docs/ http://www.postgresql.org/docs/ landing page is made even less necessary since the 'interactive' documentation already has links at the top to other point versions. Throw in a minimal sidebar and you could kill the landing page without losing any of the functionality. Of course, Postgres has been around longer, and their last major website redesign probably pre-dates the entire existence of the other two websites altogether[1], but that has no bearing on which website is the least intimidating to newcomers. If postgres sees fit to make their website less intimidating to newcomers, then their work is cut out for them. [1] Confirmed via Internet Archive's Wayback Machine. The last postgresql.org redisign was complete by early 2006. Mongo and ReThink websites showed up, in minimal form, in late 2008 and early 2009 respectively.