Re: User documentation vs Official Docs

On Tue, Jul 17, 2018, 3:33 AM Joshua D. Drake <jd(at)commandprompt(dot)com> wrote:

> -general.
>
> Over the last year as I have visited many meetups and interacted with
> people at conferences etc... There are three prevailing issues that
> continue to come up in contributing to the community. This email is
> about one of them. Where is the "user" documentation? The official
> documentation is awesome, if you know what you are doing. It is not
> particularly useful for HOWTO style docs. There is some user
> documentation in the wiki but let's be honest, writing a
> blog/article/howto in a wiki is a pain in the butt.
>
> What does the community think about a community run, community
> organized, sub project for USER documentation? This type of
> documentation would be things like, "10 steps to configure replication",
> "Dumb simple Postgres backups", "5 things to NEVER do with Postgres". I
> imagine we would sort it by version (9.6/10.0 etc...) as well as break
> it down via type (Administration, Tuning, Gotchas) etc...
>
> What do we think?
>
> Thanks!
>
> JD
>
>
> --
> Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
> *** A fault and talent of mine is to tell it exactly how it is. ***
> PostgreSQL centered full stack support, consulting and development.
> Advocate: @amplifypostgres || Learn: https://postgresconf.org
> ***** Unless otherwise stated, opinions are my own. *****
>
>
One thing I recall very fondly about the early days of the Lamp stack was
that the official documentation of PHP and MySQL was augmented with user
created practical examples. It was still reference documentation organized
by command or function, but in a comment-like section underneath the formal
docs were user provided short practical examples of how the command would
be used in real situations. One was able to teach themselves how to build a
dynamic website front ending a database just by exploring the core docs and
reading the examples.

-- Ben Scherrey