Re: User documentation vs Official Docs

On 07/20/2018 04:48 PM, Joshua D. Drake wrote:
> On 07/20/2018 03:59 PM, Alvaro Herrera wrote:
>>
>> I don't see why we need this thread to continue.  This sounds like
>> somebody looking for a solution when they don't yet know what the
>> problem is.
>
> Unfortunately, you don't understand the problem which is why this thread
> is happening on -general and not -hackers. The problem is simple as
> illustrated, our user documentation is less than stellar for those
> trying to solve specific problems. This isn't a new problem nor is it
> one that is not communicated. I hear the issue from users ever single
> time I speak or attend a conference/meetup.

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:

https://www.postgresql.org/docs/10/static/tutorial-start.html

shows a start in that direction. To me this would be the place for folks
to contribute. I personally would not have a problem including non-core
sections as well. We deal with that on --general all the time, so it
would seem to be fair game.

>
> I was hoping to get the -general community to step and build some
> recipes and howto articles without at the same time dictating the
> solution. That's a good thing because a non-dictated solution is likely
> to have more strength.
>
> The wiki is a terrible choice but if that is where the community thinks
> it should go, I welcome people starting to contribute in a structured
> fashion to the wiki. I hope it works out well.
>
> JD
>

--
Adrian Klaver
adrian(dot)klaver(at)aklaver(dot)com