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