User documentation vs Official Docs
-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. *****
On 07/16/2018 01:32 PM, Joshua D. Drake 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?
Not sure this is much different from the Wiki unless:
Who is going to?:
1) Run/maintain it.
2) Get people to contribute.
3) Edit new content, clean up old content
Thanks!
JD
--
Adrian Klaver
adrian.klaver@aklaver.com
Joshua D. Drake schrieb am 16.07.2018 um 22:32:
-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 about: https://en.wikibooks.org/wiki/PostgreSQL
On Tue, Jul 17, 2018, 3:33 AM Joshua D. Drake <jd@commandprompt.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
On 07/16/2018 01:39 PM, Adrian Klaver wrote:
Not sure this is much different from the Wiki unless:
The wiki is certainly "a place" that can be used for this but the wiki
takes a lot of effort to find things on it, manage it etc...
Who is going to?:
1) Run/maintain it.
Well this is a community. The hope would be that the community would
step up. As a proposer (and writer) I am certainly willing to participate.
2) Get people to contribute.
I don't think this is nearly as difficult except if we create artificial
barriers to contribution (writing in the wiki is a highly subpar
experience).
3) Edit new content, clean up old content
So some of this could be original content, some of it could just be
links to various blogs/articles that already exist and some could be
maintenance. However, I see maintenance as a secondary issue because we
would publish based on version. If someone wrote an article for 9.6 it
may or may not apply for 11 but that doesn't matter. People are always
generating new content.
JD
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. *****
"Joshua D. Drake" <jd@commandprompt.com> writes:
On 07/16/2018 01:39 PM, Adrian Klaver wrote:
Not sure this is much different from the Wiki unless:
The wiki is certainly "a place" that can be used for this but the wiki
takes a lot of effort to find things on it, manage it etc...
You haven't exactly explained how that wouldn't be equally true of
this hypothetical new thing.
regards, tom lane
Greetings,
* Benjamin Scherrey (scherrey@proteus-tech.com) wrote:
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.
We have a place for this to go, in the official docs, already split out
by version, and it starts here:
https://www.postgresql.org/docs/10/static/tutorial-start.html
Adding more to that certainly sounds good to me.
So, for my 2c, at least, "patches welcome."
Drive-by comments saying that we need a place for this, when we already
have one, and saying that the community should develop it, while not
acknowledging or contributing to what we already have, does not strike
me as particularly useful.
We tried having a comment area on the docs and those ultimately ended up
being... less than ideal. I'm not anxious to repeat that experiment.
I'm glad it worked for other communities, but it didn't work for us and
we have a good bit of history to show that.
The best way to improve that section of the docs is to write up good
user example-based documentation and submit it as patches. I'd
certainly be happy to see that and to try and help by moving such
patches forward to commit.
Thanks!
Stephen
On 07/16/2018 01:48 PM, Joshua D. Drake wrote:
On 07/16/2018 01:39 PM, Adrian Klaver wrote:
Not sure this is much different from the Wiki unless:
The wiki is certainly "a place" that can be used for this but the wiki
takes a lot of effort to find things on it, manage it etc...Who is going to?:
1) Run/maintain it.
Well this is a community. The hope would be that the community would
step up. As a proposer (and writer) I am certainly willing to participate.
In theory a nice idea, but community encompasses everybody and when it
comes to organization everybody = nobody. Without some sort of editorial
board running this then we are back to the Wiki.
2) Get people to contribute.
I don't think this is nearly as difficult except if we create artificial
barriers to contribution (writing in the wiki is a highly subpar
experience).
Not difficult, but folks will write about what they are interested in
which is not necessarily what users are looking for.
3) Edit new content, clean up old content
So some of this could be original content, some of it could just be
links to various blogs/articles that already exist and some could be
maintenance. However, I see maintenance as a secondary issue because we
would publish based on version. If someone wrote an article for 9.6 it
may or may not apply for 11 but that doesn't matter. People are always
generating new content.
Actually I see maintenance as a big if not the primary issue. The only
thing worse then no docs are docs that are not vetted/maintained. The
list is full of posts from folks that got information from dubious
sources and did things in error. If this project is to be useful then
the quality of the information should match that of the official
documentation and that is a high standard.
JD
Thanks!
JD
--
Adrian Klaver
adrian.klaver@aklaver.com
On 07/16/2018 01:59 PM, Stephen Frost wrote:
We have a place for this to go, in the official docs, already split out
by version, and it starts here:https://www.postgresql.org/docs/10/static/tutorial-start.html
Adding more to that certainly sounds good to me.
I didn't know that existed. I will take a look.
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. *****
On 07/16/2018 02:22 PM, Joshua D. Drake wrote:
On 07/16/2018 01:59 PM, Stephen Frost wrote:
We have a place for this to go, in the official docs, already split out
by version, and it starts here:https://www.postgresql.org/docs/10/static/tutorial-start.html
Adding more to that certainly sounds good to me.
I didn't know that existed. I will take a look.
Well now that I see it is just the "tutorial" in the official docs, I
disagree that is the correct place to start. At least not if it is going
to ship with the 1000+ pages of documentation we already have. What I am
envisioning is something with a strong SEO that gives pointed and direct
information about solving a specific problem. A tutorial book could
certainly do that as could (what I am really talking about) is Postgres
recipes or something like that.
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. *****
On Mon, Jul 16, 2018 at 5:44 PM, Joshua D. Drake <jd@commandprompt.com>
wrote:
On 07/16/2018 02:22 PM, Joshua D. Drake wrote:
On 07/16/2018 01:59 PM, Stephen Frost wrote:
We have a place for this to go, in the official docs, already split out
by version, and it starts here:https://www.postgresql.org/docs/10/static/tutorial-start.html
Adding more to that certainly sounds good to me.
I didn't know that existed. I will take a look.
Well now that I see it is just the "tutorial" in the official docs, I
disagree that is the correct place to start. At least not if it is going to
ship with the 1000+ pages of documentation we already have. What I am
envisioning is something with a strong SEO that gives pointed and direct
information about solving a specific problem. A tutorial book could
certainly do that as could (what I am really talking about) is Postgres
recipes or something like that.
I didn't know it existed either, mostly because I know how to ask google to
do things, and the things I need to know are not covered here (yet). This
does seem to me to be the ideal place to add more how to documentation to
augment all the reference docs we have.
As for some "strong SEO" I think already the top hit for almost everything
I seek postgres related is the official manual, so it seems to have good
SEO. The only big improvement would be somehow to tell google to only show
me the newest version of the manual, not all of the older ones too, for the
same page.
On 07/16/2018 02:54 PM, Vick Khera wrote:
On Mon, Jul 16, 2018 at 5:44 PM, Joshua D. Drake <jd@commandprompt.com
<mailto:jd@commandprompt.com>> wrote:On 07/16/2018 02:22 PM, Joshua D. Drake wrote:
On 07/16/2018 01:59 PM, Stephen Frost wrote:
We have a place for this to go, in the official docs,
already split out
by version, and it starts here:https://www.postgresql.org/docs/10/static/tutorial-start.html
<https://www.postgresql.org/docs/10/static/tutorial-start.html>As for some "strong SEO" I think already the top hit for almost
everything I seek postgres related is the official manual, so it seems
to have good SEO. The only big improvement would be somehow to tell
google to only show me the newest version of the manual, not all of
the older ones too, for the same page.
You aren't wrong on how its ranked but here is an example of what I am
talking about with SEO:
Search:
postgresql backups
For me, the first three are the docs which are not very useful if you
just want backups that just work (unless you are someone like you and I
who are using the docs for reference not howto). The fourth link is this
one:
https://www.compose.com/articles/postgresql-backups-and-everything-you-need-to-know/
Which is a great article but also isn't what I am thinking about. What I
am thinking about is articles like this:
https://www.commandprompt.com/blog/a_better_backup_with_postgresql_using_pg_dump/
Which in this case is clearly out of date but provides context of what I
am trying to achieve.
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. *****
Joshua D. Drake <jd@commandprompt.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
On Mon, Jul 16, 2018 at 1:32 PM, Joshua D. Drake <jd@commandprompt.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?
Politely tell them to buy some of the many well written books that are
available on these very topics...
David J.
On 07/16/2018 03:07 PM, Tim Cross wrote:
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.
Well I threw all this out there to start a discussion on how best this
could be done. What *I* would do is either create a series of templates
to be followed that we would push to HTML and PDF. That could be done
with a form and TinyMCE or we could use LibreOffice/Office templates.
However, I don't know that the community would buy into the office
template idea (thus seeking feedback).
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?
First, my assumption is that this project would be done within the .Org
infrastructure and if the community thinks that we should just use
DocBook that is certainly an option (although adhering to something like
Docbook Simple may be best).
Thanks,
JD
Tim
--
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. *****
On 07/16/2018 03:14 PM, David G. Johnston wrote:
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?
Politely tell them to buy some of the many well written books that
are available on these very topics...
Politely tell them to buy a license to MSSQl...
Kind of misses the whole point doesn't it?
JD
David J.
--
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. *****
On Mon, Jul 16, 2018 at 3:19 PM, Joshua D. Drake <jd@commandprompt.com>
wrote:
On 07/16/2018 03:14 PM, David G. Johnston wrote:
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?
Politely tell them to buy some of the many well written books that are
available on these very topics...Politely tell them to buy a license to MSSQl...
Kind of misses the whole point doesn't it?
I'm going for practicality over idealism here. That some of the best
written material for learning how to be an application developer or DBA is
presently really only available in the forms of books is a fact of our
existence. I frankly don't have a problem that there isn't a "free beer"
resource available to complete with it.
I'm all for continual improvement but color me doubtful that there is
enough desire and discipline here to invent and then maintain a
high-maintenance system. So, yes, I am intentionally trying to avoid the
trap that is problem that you want to solve by suggesting forgetting the
revolution and instead coming at the problem from an entirely different
angle and working to evolve the equilibrium that presently exists.
David J.
On 07/16/2018 03:18 PM, Joshua D. Drake wrote:
On 07/16/2018 03:07 PM, Tim Cross wrote:
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.Well I threw all this out there to start a discussion on how best this
could be done. What *I* would do is either create a series of templates
to be followed that we would push to HTML and PDF. That could be done
with a form and TinyMCE or we could use LibreOffice/Office templates.
However, I don't know that the community would buy into the office
template idea (thus seeking feedback).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?First, my assumption is that this project would be done within the .Org
infrastructure and if the community thinks that we should just use
DocBook that is certainly an option (although adhering to something like
Docbook Simple may be best).
All the above is cool and everything, but is putting the cart before the
horse. To me to make this work the following needs to happen:
1) Create an editorial board. This group of people would determine the
answers to the questions above. They would also develop the framework
for what needs covered. This would be based on what users want to see.
Then a call for contributors could be made.
2) The other thing the editorial board would do is create list of
qualified peer reviewers. These folks would then review the
contributions and give feedback. On successfully passing a review a
contribution would go into the documentation.
3) Some combination of the editorial board/peer reviewers/other
volunteers would periodically go over existing documentation to
remove/update stale content.
Thanks,
JD
Tim
--
Adrian Klaver
adrian.klaver@aklaver.com
On 07/16/2018 03:37 PM, David G. Johnston wrote:
On Mon, Jul 16, 2018 at 3:19 PM, Joshua D. Drake <jd@commandprompt.com
<mailto:jd@commandprompt.com>>wrote:On 07/16/2018 03:14 PM, David G. Johnston wrote:
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?
Politely tell them to buy some of the many well written books
that are available on these very topics...Politely tell them to buy a license to MSSQl...
Kind of misses the whole point doesn't it?
I'm going for practicality over idealism here. That some of the best
written material for learning how to be an application developer or
DBA is presently really only available in the forms of books is a fact
of our existence. I frankly don't have a problem that there isn't a
"free beer" resource available to complete with it.
Fair enough but what about those that cant afford it? I think us in the
Western World tend to forget that by far the majority of users cant
afford a latte from Starbucks let alone a 60.00 USD dead tree.
I'm all for continual improvement but color me doubtful that there is
enough desire and discipline here to invent and then maintain a
high-maintenance system. So, yes, I am intentionally trying to avoid
the trap that is problem that you want to solve by suggesting
forgetting the revolution and instead coming at the problem from an
entirely different angle and working to evolve the equilibrium that
presently exists.
Hey, don't get me wrong. I get your point but I also know what I hear
and I hear from *lots* of users because of PostgresConf and all the
meetups. I am just trying to resolve a problem that exists for that
community. Think of this (if we can figure out how to pull this off):
User on StackOverflow says, "How do I do X", someone answers with a
direct link to a recipe on PostgreSQL.Org that tells them exactly how to
do X (with caveats of course). There isn't much more user friendly than
that.
I am also not suggesting this wouldn't be work but it is also work a lot
more people can do than people that can submit a patch to -hackers
(exponentially so).
IMO,
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. *****
On 07/16/2018 04:33 PM, Adrian Klaver wrote:
First, my assumption is that this project would be done within the
.Org infrastructure and if the community thinks that we should just
use DocBook that is certainly an option (although adhering to
something like Docbook Simple may be best).All the above is cool and everything, but is putting the cart before
the horse. To me to make this work the following needs to happen:1) Create an editorial board. This group of people would determine the
answers to the questions above. They would also develop the framework
for what needs covered. This would be based on what users want to see.
Then a call for contributors could be made.2) The other thing the editorial board would do is create list of
qualified peer reviewers. These folks would then review the
contributions and give feedback. On successfully passing a review a
contribution would go into the documentation.3) Some combination of the editorial board/peer reviewers/other
volunteers would periodically go over existing documentation to
remove/update stale content.
I did it! Want to help? I think if we got together 5-7 people and came
up with a proposal we could submit to -www/-core and get some buy in.
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. *****
