Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

I think it is hard for me to explain, because actually -> I <- prefer the Postgres documentation. However, I realized that was because it is fundamentally a man page. For someone who is exploring Postgres, or for someone who comes from other databases, it is way too abridged.

A simple example is the getting started part http://dev.mysql.com/doc/refman/5.5/en/creating-database.htm... vs http://www.postgresql.org/docs/9.2/interactive/tutorial-crea... Notice that Postgres has switched to using system commands like "createdb" while mysql sticks to SQL - there is a perfectly viable way to do this in Postgres using SQL, but perhaps the author didnt want to go directly to explaining template databases (which is simpler IMHO).

Go and ask someone who is new to both Mysql and Postgres to read these sections. Based on the distro they are on, you have completely lost them between the complexities of the OS vs the database Here is an example of the kind of confusions that result - http://superuser.com/questions/220771/how-can-i-create-a-dat...

Check this section out - http://dev.mysql.com/doc/refman/5.5/en/privilege-system.html. The reason why I am picking up client authentication example is that this where 90% of beginner postgres problems occur: they happened to me and they happen to every other first timer. Is postgres more complicated ? No, but you need to explain it better. I find this to be a much more useful tutorial to point first timers to, even if they are not on Ubuntu : https://help.ubuntu.com/10.04/serverguide/postgresql.html



I would say that I have the exact opposite opinion of you: the manual is not so great at narration because it is really extensive. Consider the example you gave: the postgres tutorial makes no assumption that you can even connect to the database or have the 'createdb' binary, and fairly exhaustively addresses each error case, whereas the MySQL tutorial at this stage presume you have a the mysql binaries and database session live already. In the stage of the tutorial that is most similar to the 'createdb' step is more similar to this page:

http://dev.mysql.com/doc/refman/5.5/en/connecting-disconnect...

Whereby it's presumed that if you cannot get a connection you should talk to your administrator and give up. That may not be bad advice: the exhaustive covering of error cases by postgres tutorial may detract from rather than enhance the exercise.

I agree that Postgres' default authentication system one uses for development -- based on the account name -- probably deserves a different kind of explanation. It's an approach considerably better that most other software that it's probably worth keeping (especially for someone who hates more passwords), in spite of figuring out a way to explain it.

All in all, I basically don't agree with the notion that it is "abridged." It could be improved, but I think you are repeatedly using these words describing the scantness of the documentation whereas I think it is borderline over-detailed as it is. Perhaps a different kind of information presentation is required, is what I think.

Although still nascent, this lack of narrative documentation is probably why Craig started writing http://postgresguide.com/. This doesn't do a good job of explaining how to install the software, but is a lot more conversational than the Postgres documentation:

http://postgresguide.com/SQL/select.html

vs

http://www.postgresql.org/docs/9.2/static/sql-select.html

Clearly, one is more complete in some sense, but it's not going to help the beginner.




Consider applying for YC's Winter 2026 batch! Applications are open till Nov 10

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: