Re: User documentation vs Official Docs

Joshua D. Drake <jd(at)commandprompt(dot)com> writes:

> -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?
>

I think encouraging user developed docs is a great idea.

However, I'm not sure how your proposal really addresses the issue. How
would your proposal deal with the "but let's be honest, writing a
blog/article/howto in a wiki is a pain in the butt" issue? Writing
decent documentation or clear examples is hard and the only thing worse
than no documentation is misleading or confusing documentation.

My only real concern would be to further fracture the PG user base. If
there are barriers preventing users from adding documentation to the
existing documents or wiki, perhaps it would be better to try and
address those first?

Tim

--
Tim Cross