Re: User documentation vs Official Docs

On Fri, Jul 20, 2018 at 05:31:40PM -0700, Adrian Klaver wrote:
> JD sit down, I am going to agree with you:) The documentation as it stands
> is very good, though it requires some fore knowledge to successfully
> navigate. On pages with a lot of content it often is not evident, to many,
> that there are actually examples at the bottom of the page. Also that the
> exceptions to the rules are called out there also. The general concept of
> presenting a task, writing a procedure to accomplish the task and pointing
> to the documentation that covers the procedure would be a helpful addition.
> It would be nice to point to something like that in a post rather then
> continually rebuilding the explanation every time a new user hits the list.
> Looking at the link posted upstream:

I am jumping in late here, but I do have some thoughts on this topic.
To me, there are three levels of information presentation:

1. Task-oriented documents
2. Exhaustive technical documentation/manuals
3. Concept-level material

I think we call agree that the Postgres documentation does very well
with #2, and we regularly get complements for its quality.

For #1, this is usually related to performing a task without requiring a
full study of the topic. For example, if I need iptables rules to block
a sunrpc attack, or use NFS over ssh, I really want some commands that I
can study and adjust to the task --- I don't want to study all the
features of these utilities to get the job done. This is an area the
docs don't cover well, but our blogs and wikis do.

For #3, this is mostly covered by books. This topic requires a lot of
explanation and high-level thinking. We have some of that in our docs,
but in general books probably do this better.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +