Обсуждение: 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.htm l
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> 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.htm l 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
-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 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 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. *****
On 07/16/2018 04:56 PM, Joshua D. Drake wrote: > >> 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! s/did/dig -- 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 2018-Jul-16, Joshua D. Drake wrote: > 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. Sounds like wiki pages could solve need this pretty conveniently. If and when the content is mature enough and migrates to the tutorial main documentation pages, the wiki pages can be replaced with redirects to those. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 07/16/2018 05:08 PM, Alvaro Herrera wrote: > > Sounds like wiki pages could solve need this pretty conveniently. If > and when the content is mature enough and migrates to the tutorial main > documentation pages, the wiki pages can be replaced with redirects to > those. Anyone who writes a lot is going to rebel against using a wiki. They are one of the worst to write in from a productivity perspective. I would rather write in Docbook, at least then I can template everything and we could have a standard xsl sheet etc... 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, 16 Jul 2018 at 20:14, Joshua D. Drake <jd@commandprompt.com> wrote: > > On 07/16/2018 05:08 PM, Alvaro Herrera wrote: > > > > Sounds like wiki pages could solve need this pretty conveniently. If > > and when the content is mature enough and migrates to the tutorial main > > documentation pages, the wiki pages can be replaced with redirects to > > those. > > Anyone who writes a lot is going to rebel against using a wiki. They are > one of the worst to write in from a productivity perspective. I would > rather write in Docbook, at least then I can template everything and we > could have a standard xsl sheet etc... Indeed. I think it would be a fine idea to have some proposals for improved examples for the tutorial pages. By putting them there, it becomes easy to reference material either in reference sections or in the manual pages on SQL commands. (As "for instances." It would also be nice to have examples that make reference to executable programs, whether pg_dump, pg_ctl, or ...) I'd be willing to help write something of the sort; if I'm to shoot my mouth off on what we ought to do, best to volunteer to actually make some of it happen. Having some small sample applications that do interesting things with different Postgres facilities seems like a neat approach. It would be interesting to have an example that makes decent use of LISTEN/NOTIFY; people keep asking how to have PostgreSQL send email, and writing a small example that handles it via queueing requests into a table, where a daemon stops in to send queued email once in a while. Another idea would be an app that captures messages into tables and enables full text search would be nice. Doing some somewhat simplistic partitioning of a perhaps large (but simplistic, so it fits into docs) data set would help motivate use of partitioning facilities. Applications need to be kept fairly tiny so that they represent good examples without being of dominant size. -- When confronted by a difficult problem, solve it by reducing it to the question, "How would the Lone Ranger handle this?"
On Jul 16, 2018, at 8:08 PM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote:On 2018-Jul-16, Joshua D. Drake wrote: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.
Sounds like wiki pages could solve need this pretty conveniently. If
and when the content is mature enough and migrates to the tutorial main
documentation pages, the wiki pages can be replaced with redirects to
those.
We’ve also tried to use the website to point to some already existing
resources to learn PostgreSQL:
Some of these includes tutorials that people have put together. If other
resources exist, I’m sure the -www team would be happy to review and
add them. We could also consider renaming the page to make it more
clear that it links to tutorials and the like.
That said, I’m sure contributions to improving the tutorial in the docs
would be well received. I figure it would just take a bit of work from people
who want to add to it. I see it being no different than getting a large patch
in, just some collaborative efforts from people who want to make it better
and some community back-and-forth.
Jonathan
On 17.07.18 02:13, Joshua D. Drake wrote: > On 07/16/2018 05:08 PM, Alvaro Herrera wrote: >> >> Sounds like wiki pages could solve need this pretty conveniently. If >> and when the content is mature enough and migrates to the tutorial main >> documentation pages, the wiki pages can be replaced with redirects to >> those. > > Anyone who writes a lot is going to rebel against using a wiki. They are > one of the worst to write in from a productivity perspective. I would > rather write in Docbook, at least then I can template everything and we > could have a standard xsl sheet etc... I don't really buy that. The wiki seems just fine for writing short to medium size how-to type articles. We already have good content of that sort in the wiki right now. It's not like there isn't going to be anyone who will rebel against any of the other tool chains that have been mentioned. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Tue, Jul 17, 2018 at 1:47 PM, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
On 17.07.18 02:13, Joshua D. Drake wrote:
> On 07/16/2018 05:08 PM, Alvaro Herrera wrote:
>>
>> Sounds like wiki pages could solve need this pretty conveniently. If
>> and when the content is mature enough and migrates to the tutorial main
>> documentation pages, the wiki pages can be replaced with redirects to
>> those.
>
> Anyone who writes a lot is going to rebel against using a wiki. They are
> one of the worst to write in from a productivity perspective. I would
> rather write in Docbook, at least then I can template everything and we
> could have a standard xsl sheet etc...
I don't really buy that. The wiki seems just fine for writing short to
medium size how-to type articles. We already have good content of that
sort in the wiki right now. It's not like there isn't going to be
anyone who will rebel against any of the other tool chains that have
been mentioned.
I think the biggest problem with the wiki for that type of content has nothing to do with the formatting, and everything to do with the structure. By definition the wiki is unstructured. One could put a structure on top of it, with proper categories and indexing pages. That's done for some info on it, but not for all. There's also a lot of outdated information.
Both those things are things that could be solved by somebody with the time and willingness to trawl through the wiki to update such things, and then to keep things updated. But keeping it updated is an equal amount of work regardless of platform. If we find somebody who wants to do that, then at least *starting out* on the wiki is a good idea. It's usually a Good Enough (TM) system. And the most common things I see people writing such things in today are Markdown (hi github!) or RST (hi Sphinx!) anyway, both of which are pretty similar to the wiki markup. Which means that the project could *start out* using the wiki, and once there is enough content to prove the idea other platforms could be looked at and it would be easy enough to migrate that data out there (even if just by copy/paste) if it becomes a need.
On 07/16/2018 04:56 PM, Joshua D. Drake wrote: > On 07/16/2018 04:33 PM, Adrian Klaver wrote: >> > > 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. Given the really discovered existence of the tutorial pages I would say that is the way to go, rather then fragment the user documentation on to another site. It would seem to meet the need for step by step instructions on common tasks. For more specialized cases adding a layer of organization to the Wiki could prove useful. I would be willing to help as needed. Contact me offline to carry on that conversation. > > JD > -- Adrian Klaver adrian.klaver@aklaver.com
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes: > On 17.07.18 02:13, Joshua D. Drake wrote: >> On 07/16/2018 05:08 PM, Alvaro Herrera wrote: >>> >>> Sounds like wiki pages could solve need this pretty conveniently. If >>> and when the content is mature enough and migrates to the tutorial main >>> documentation pages, the wiki pages can be replaced with redirects to >>> those. >> >> Anyone who writes a lot is going to rebel against using a wiki. They are >> one of the worst to write in from a productivity perspective. I would >> rather write in Docbook, at least then I can template everything and we >> could have a standard xsl sheet etc... > > I don't really buy that. The wiki seems just fine for writing short to > medium size how-to type articles. We already have good content of that > sort in the wiki right now. It's not like there isn't going to be > anyone who will rebel against any of the other tool chains that have > been mentioned. If using web widgets to author content on the wiki is the main impediment for contributing content, maybe we should see if the wiki provides alternative access methods. I've used wikis in the past which allowed users to upload content via xmlrpc, api etc. Perhaps something similar could be made available for those making significant contributions or to a select few 'curators' who could accept content from others. If it is the interface that is the problem, we should try to address that first rather than simply switching to something new which will have its own problems. However, I don't know if this is the case or not. Tim -- Tim Cross
Greetings Vick, * Vick Khera (vivek@khera.org) wrote: > 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. Agreed. It'd be great to have more tutorials in our official documentation. > 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. Agreed, and there's ongoing work to improve the situation regarding the different versions of the manual and getting Google to show the "current" URL in preference to the other versions. Thanks! Stephen
Вложения
On 2018-07-18 08:09:35 +1000, Tim Cross wrote:
> If using web widgets to author content on the wiki is the main
> impediment for contributing content, maybe we should see if the wiki
> provides alternative access methods. I've used wikis in the past which
> allowed users to upload content via xmlrpc, api etc. Perhaps something
> similar could be made available for those making significant
> contributions or to a select few 'curators' who could accept content
> from others.
There are also browser plugins like It's all text, textern, wasavi, etc.
which allow the user to use a real text editor instead of a text area.
hp
--
_ | Peter J. Holzer | we build much bigger, better disasters now
|_|_) | | because we have much more sophisticated
| | | hjp@hjp.at | management tools.
__/ | http://www.hjp.at/ | -- Ross Anderson <https://www.edge.org/>
Вложения
On 07/19/2018 11:04 AM, Peter J. Holzer wrote: > On 2018-07-18 08:09:35 +1000, Tim Cross wrote: >> If using web widgets to author content on the wiki is the main >> impediment for contributing content, maybe we should see if the wiki >> provides alternative access methods. I've used wikis in the past which >> allowed users to upload content via xmlrpc, api etc. Perhaps something >> similar could be made available for those making significant >> contributions or to a select few 'curators' who could accept content >> from others. > There are also browser plugins like It's all text, textern, wasavi, etc. > which allow the user to use a real text editor instead of a text area. > > hp > Keep in mind that Chrome broke "It's all text" compatibility, at least with emacs and now it's done via "Edit with Emacs". This in my experience is a step backwards from "It's all text".
On 2018-07-19 11:43:18 -0600, Rob Sargent wrote:
> On 07/19/2018 11:04 AM, Peter J. Holzer wrote:
> > On 2018-07-18 08:09:35 +1000, Tim Cross wrote:
> > > If using web widgets to author content on the wiki is the main
> > > impediment for contributing content, maybe we should see if the wiki
> > > provides alternative access methods. I've used wikis in the past which
> > > allowed users to upload content via xmlrpc, api etc. Perhaps something
> > > similar could be made available for those making significant
> > > contributions or to a select few 'curators' who could accept content
> > > from others.
> > There are also browser plugins like It's all text, textern, wasavi, etc.
> > which allow the user to use a real text editor instead of a text area.
> >
> Keep in mind that Chrome broke "It's all text" compatibility, at least with
> emacs and now it's done via "Edit with Emacs". This in my experience is a
> step backwards from "It's all text".
Oh, Chrome, too?
Firefox also broke compatibility with a lot of add-ons recently ("It's
all text" among them). So I switched to textern, which was a bit more
complicated to set up, but otherwise works almost the same.
But yeah, browser add-ons have a certain tendency to succumb to bit-rot,
so they are nice tools for a user but not something a service provider
should depend on.
hp
--
_ | Peter J. Holzer | we build much bigger, better disasters now
|_|_) | | because we have much more sophisticated
| | | hjp@hjp.at | management tools.
__/ | http://www.hjp.at/ | -- Ross Anderson <https://www.edge.org/>
Вложения
>> Politely tell them to buy some of the many well written books that are available on these very topics...
>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.
Seriously? So someone can afford a $500 computer ( in addition to accessories ), but they wouldn't be able to afford a $60 book (which BTW, there are several for lesser amount) ?
>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.
Seriously? So someone can afford a $500 computer ( in addition to accessories ), but they wouldn't be able to afford a $60 book (which BTW, there are several for lesser amount) ?
I have been monitoring this thread for many days now. It originally started as a request for users to write a separate user tutorial. But a tutorial for what? That was never stated.
What exactly is missing from the official documentation? Isn't it the purpose of pgsql-general to answer user questions? Why is there such a great need to create yet a third form to guide
PostgreSQL users, which would only end up being included in a google search anyway, with no guarantee of priority?
Peter J. Holzer <hjp-pgsql@hjp.at> writes: > On 2018-07-18 08:09:35 +1000, Tim Cross wrote: >> If using web widgets to author content on the wiki is the main >> impediment for contributing content, maybe we should see if the wiki >> provides alternative access methods. I've used wikis in the past which >> allowed users to upload content via xmlrpc, api etc. Perhaps something >> similar could be made available for those making significant >> contributions or to a select few 'curators' who could accept content >> from others. > > There are also browser plugins like It's all text, textern, wasavi, etc. > which allow the user to use a real text editor instead of a text area. > > hp +1. Should have remember that option given I have such a plugin myself and use it often! -- Tim Cross
On Thu, Jul 19, 2018 at 11:35 AM Melvin Davidson <melvin6925@gmail.com> wrote:
>> Politely tell them to buy some of the many well written books that are available on these very topics...
>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.
Seriously? So someone can afford a $500 computer ( in addition to accessories ), but they wouldn't be able to afford a $60 book (which BTW, there are several for lesser amount) ?
Seriously? With global median household income at less than $200 / week (and ranging by country from $2 to $400)[1], you can't understand that $60 could be a barrier for lots of people? And computers can be had for far less than $500, even before you get to used or refurbished. Then again people might use shared, university or library computers. You've nicely illustrated Josh's point which you yourself quoted: "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."
My comment, BTW, applies to all versions of Postgresql, whether current, unsupported or yet-to-be-developed.
Cheers,
Ken
AGENCY Software
A Free Software data system
By and for non-profits
(253) 245-3801
learn more about AGENCY or
follow the discussion.
On Thu, Jul 19, 2018 at 8:09 PM, Ken Tanzer <ken.tanzer@gmail.com> wrote:
--On Thu, Jul 19, 2018 at 11:35 AM Melvin Davidson <melvin6925@gmail.com> wrote:>> Politely tell them to buy some of the many well written books that are available on these very topics...
>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.
Seriously? So someone can afford a $500 computer ( in addition to accessories ), but they wouldn't be able to afford a $60 book (which BTW, there are several for lesser amount) ?Seriously? With global median household income at less than $200 / week (and ranging by country from $2 to $400)[1], you can't understand that $60 could be a barrier for lots of people? And computers can be had for far less than $500, even before you get to used or refurbished. Then again people might use shared, university or library computers. You've nicely illustrated Josh's point which you yourself quoted: "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."My comment, BTW, applies to all versions of Postgresql, whether current, unsupported or yet-to-be-developed.Cheers,KenAGENCY SoftwareA Free Software data systemBy and for non-profits(253) 245-3801learn more about AGENCY orfollow the discussion.
> Then again people might use shared, university or library computers
Would you please be so kind as to inform us which university or library allows users to install software on a _shared_ computer.
BTW, since you mention library, that is an excellent way to have the books ordered and shared.>FOR FREE<. AFAIK, all that is required is for
someone to request the library purchase the book, to be used for shared learning.
--
Melvin Davidson
Maj. Database & Exploration Specialist
Universe Exploration Command – UXC
Employment by invitation only!
Maj. Database & Exploration Specialist
Universe Exploration Command – UXC
Employment by invitation only!
On 07/19/2018 05:43 PM, Melvin Davidson wrote: > > > > > > Then again people might use shared, university or library computers > Would you please be so kind as to inform us which university or library > allows users to install software on a _shared_ computer. Pretty sure Ken was referring to looking up documentation, not running Postgres. > > BTW, since you mention library, that is an excellent way to have the > books ordered and shared.>FOR FREE<. AFAIK, all that is required is for > someone to request the library purchase the book, to be used for shared > learning. > > > -- > *Melvin Davidson** > Maj. Database & Exploration Specialist** > Universe Exploration Command – UXC*** > Employment by invitation only! -- Adrian Klaver adrian.klaver@aklaver.com
On 07/19/2018 05:54 PM, Adrian Klaver wrote: > On 07/19/2018 05:43 PM, Melvin Davidson wrote: >> >> > >> >> >> > Then again people might use shared, university or library computers >> Would you please be so kind as to inform us which university or >> library allows users to install software on a _shared_ computer. > > Pretty sure Ken was referring to looking up documentation, not running > Postgres. Or on computer lab machines. > >> >> BTW, since you mention library, that is an excellent way to have the >> books ordered and shared.>FOR FREE<. AFAIK, all that is required is for >> someone to request the library purchase the book, to be used for >> shared learning. >> >> >> -- >> *Melvin Davidson** >> Maj. Database & Exploration Specialist** >> Universe Exploration Command – UXC*** >> Employment by invitation only! > > -- Adrian Klaver adrian.klaver@aklaver.com
On Thu, Jul 19, 2018 at 8:54 PM, Adrian Klaver <adrian.klaver@aklaver.com> wrote:
On 07/19/2018 05:43 PM, Melvin Davidson wrote:
> Then again people might use shared, university or library computers
Would you please be so kind as to inform us which university or library allows users to install software on a _shared_ computer.
Pretty sure Ken was referring to looking up documentation, not running Postgres.
BTW, since you mention library, that is an excellent way to have the books ordered and shared.>FOR FREE<. AFAIK, all that is required is for
someone to request the library purchase the book, to be used for shared learning.
--
*Melvin Davidson**
Maj. Database & Exploration Specialist**
Universe Exploration Command – UXC***
Employment by invitation only!
--
Adrian Klaver
adrian.klaver@aklaver.com
> Pretty sure Ken was referring to looking up documentation, not running Postgres.
That does not correlate. To have the need to look up documentation implies that the user has a computer running PostgreSQL.
As universities DO NOT ALLOW software to be installed on shared computers, and this is the case especially in a library, it implies
the user has their own computer. As libraries allow users/citizens to request books be purchased >at no cost to the user/citizen, the
argument that someone cannot afford a book is now a moot point.
--
Melvin Davidson
Maj. Database & Exploration Specialist
Universe Exploration Command – UXC
Employment by invitation only!
Maj. Database & Exploration Specialist
Universe Exploration Command – UXC
Employment by invitation only!
On Thu, Jul 19, 2018 at 5:43 PM Melvin Davidson <melvin6925@gmail.com> wrote:
> Then again people might use shared, university or library computersWould you please be so kind as to inform us which university or library allows users to install software on a _shared_ computer.
Well, just sticking to a quick Google, the Western world and my home town, the University of Washington appears to do so, though this is from 2013:
BTW, since you mention library, that is an excellent way to have the books ordered and shared.>FOR FREE<. AFAIK, all that is required is forsomeone to request the library purchase the book, to be used for shared learning.
Probably depends on the library and their level of funding
BTW, I think more tutorials and recipes are a great idea, though am agnostic as to the forum/format used.
Cheers,
Ken
-- AGENCY Software
A Free Software data system
By and for non-profits
(253) 245-3801
learn more about AGENCY or
follow the discussion.
On 07/19/2018 06:58 PM, Adrian Klaver wrote: > On 07/19/2018 05:54 PM, Adrian Klaver wrote: >> On 07/19/2018 05:43 PM, Melvin Davidson wrote: >>> >>> >> >>> >>> >>> > Then again people might use shared, university or library computers >>> Would you please be so kind as to inform us which university or >>> library allows users to install software on a _shared_ computer. >> >> Pretty sure Ken was referring to looking up documentation, not >> running Postgres. > > Or on computer lab machines. > And using psql on such available devices. Hopefully this new set of docs will have something for that usage too? >> >>> >>> BTW, since you mention library, that is an excellent way to have the >>> books ordered and shared.>FOR FREE<. AFAIK, all that is required is >>> for >>> someone to request the library purchase the book, to be used for >>> shared learning. >>> >>> >>> -- >>> *Melvin Davidson** >>> Maj. Database & Exploration Specialist** >>> Universe Exploration Command – UXC*** >>> Employment by invitation only! >> >> > >
Our University provides access to a Linux server for any student (not just those in data science etc) or staff member and that computer has Postgres available for anyone who want to use it. The server is also accessible remotely (80% of our student base is remote/on-line). You also get a shell account and can install any software which can be installed and run from that account. At another University I do some work for, they have moved to a virtual environment, where students are able to spin up a virtual computer on demand and have full access to install whatever software they like (though there are some constraints on what can be setup to 'persist' across instances. You could install PG, but I'm not sure if it would be restored next time you spin up hyour virtual server).
From personal experience, I can say that when I was a student, a $60 book was very difficult to justify/afford and I greatly valued on-line resources at that time. I made extensive use of the library, but obtaining specific books was not as easy as asking for them - the library has limited space and can only maintain collections on a demand basis, so you were unlikely to get a book just based on request.
A further aspect about on-line resources not yet mentioned is the accessibility aspect. As a blind programmer, I know the huge benefits of electronic resources compered to dead trees!
Tim
On Fri, 20 Jul 2018 at 11:03, Melvin Davidson <melvin6925@gmail.com> wrote:
On Thu, Jul 19, 2018 at 8:54 PM, Adrian Klaver <adrian.klaver@aklaver.com> wrote:On 07/19/2018 05:43 PM, Melvin Davidson wrote:
> Then again people might use shared, university or library computers
Would you please be so kind as to inform us which university or library allows users to install software on a _shared_ computer.
Pretty sure Ken was referring to looking up documentation, not running Postgres.
BTW, since you mention library, that is an excellent way to have the books ordered and shared.>FOR FREE<. AFAIK, all that is required is for
someone to request the library purchase the book, to be used for shared learning.
--
*Melvin Davidson**
Maj. Database & Exploration Specialist**
Universe Exploration Command – UXC***
Employment by invitation only!
--
Adrian Klaver
adrian.klaver@aklaver.com
> Pretty sure Ken was referring to looking up documentation, not running Postgres.That does not correlate. To have the need to look up documentation implies that the user has a computer running PostgreSQL.As universities DO NOT ALLOW software to be installed on shared computers, and this is the case especially in a library, it impliesthe user has their own computer. As libraries allow users/citizens to request books be purchased >at no cost to the user/citizen, theargument that someone cannot afford a book is now a moot point.
--Melvin Davidson
Maj. Database & Exploration Specialist
Universe Exploration Command – UXC
Employment by invitation only!
regards,
Tim
--
Tim CrossOn Thu, 19 Jul 2018 21:02:16 -0400, Melvin Davidson <melvin6925@gmail.com> wrote: >As universities DO NOT ALLOW software to be installed on shared computers, >and this is the case especially in a library, it implies the user has >their own computer. Many (most?) universities do allow students to install and run software locally under their own accounts. Of course, that doesn't help a visitor using a lab or library computer. >As libraries allow users/citizens to request books be purchased at no >cost to the user/citizen, the argument that someone cannot afford a book >is now a moot point. Libraries can't afford to purchase everything anyone might want. However, libraries lend to one another as well as to their patrons. You always can ask your library to borrow the book from some other library that does have it. Most libraries belong to one or more inter-library lending networks. [Of course, there is no telling how long it will take to get a book that way - you may wait months for something that's hard to find, or if you happen to be far from a decent sized city.] Another nice thing: often when the book needs to be ordered from another library, you can keep it checked out longer than if it came from the local collection. E.g., my local library allows (most) books to be checked out for up to 2 weeks. Specially ordered books, however, can be checked out for up to 5 weeks. These times may not be typical, but wherever I have been, the libraries have allowed for keeping specially ordered books longer. YMMV, George
On 07/20/2018 10:38 AM, George Neuner wrote: > >> As libraries allow users/citizens to request books be purchased at no >> cost to the user/citizen, the argument that someone cannot afford a book >> is now a moot point. This thread is getting off topic. The tl;dr; of this particular subthread is that we are not here just for the relatively rich Western World, students or not (although I certainly appreciate that pain). We are an International community with varying levels of financial capabilities. If we want to enable the *entire* community to succeed with PostgreSQL we have to have resources that are Free (as in Beer and Software). Back to the original idea, it would be great if those participating would be willing to help even a little in determining an actual direction to take this. 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/20/2018 11:45 AM, Joshua D. Drake wrote: > On 07/20/2018 10:38 AM, George Neuner wrote: >> >>> As libraries allow users/citizens to request books be purchased at no >>> cost to the user/citizen, the argument that someone cannot afford a book >>> is now a moot point. > > This thread is getting off topic. The tl;dr; of this particular > subthread is that we are not here just for the relatively rich Western > World, students or not (although I certainly appreciate that pain). We > are an International community with varying levels of financial > capabilities. If we want to enable the *entire* community to succeed > with PostgreSQL we have to have resources that are Free (as in Beer and > Software). > > Back to the original idea, it would be great if those participating > would be willing to help even a little in determining an actual > direction to take this. I would say that discussion should take place in --docs: https://www.postgresql.org/list/pgsql-docs/ > > > Thanks, > > > JD > > > -- Adrian Klaver adrian.klaver@aklaver.com
On 2018-Jul-20, Adrian Klaver wrote: > On 07/20/2018 11:45 AM, Joshua D. Drake wrote: > > Back to the original idea, it would be great if those participating > > would be willing to help even a little in determining an actual > > direction to take this. > > I would say that discussion should take place in --docs: > > https://www.postgresql.org/list/pgsql-docs/ 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. If people want to contribute, there are already some places where they can do so. Articles can be drafted in the wiki initially or, heck, even sites like StackOverflow[1], and if something gets to a level so great that they think it should be enshrined in DocBook, they can turn it into a documentation patch. [1] for extra points, write in SO and then add a link to the question to FAQ in the wiki. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Fri, Jul 20, 2018 at 6:59 PM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
On 2018-Jul-20, Adrian Klaver wrote:
> On 07/20/2018 11:45 AM, Joshua D. Drake wrote:
> > Back to the original idea, it would be great if those participating
> > would be willing to help even a little in determining an actual
> > direction to take this.
>
> I would say that discussion should take place in --docs:
>
> https://www.postgresql.org/list/pgsql-docs/
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.
If people want to contribute, there are already some places where they
can do so. Articles can be drafted in the wiki initially or, heck, even
sites like StackOverflow[1], and if something gets to a level so great
that they think it should be enshrined in DocBook, they can turn it into
a documentation patch.
[1] for extra points, write in SO and then add a link to the question to
FAQ in the wiki.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
> This sounds like somebody looking for a solution when they don't yet know what the problem is.
+1
--
Melvin Davidson
Maj. Database & Exploration Specialist
Universe Exploration Command – UXC
Employment by invitation only!
Maj. Database & Exploration Specialist
Universe Exploration Command – UXC
Employment by invitation only!
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. 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 -- 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. *****
Greetings, * Alvaro Herrera (alvherre@2ndquadrant.com) 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. > > If people want to contribute, there are already some places where they > can do so. Articles can be drafted in the wiki initially or, heck, even > sites like StackOverflow[1], and if something gets to a level so great > that they think it should be enshrined in DocBook, they can turn it into > a documentation patch. +1. I'd personally like to see improvements to the tutorials, and patches could certainly be submitted or specific ideas discussed over on -docs. A few ideas around that would be: - Setting up async replication - Setting up sync replication, with quorum-based sync - Cascading replication - Parallel pg_dump-based backup/restore (with pg_dumpall for globals) - Using various important extensions (pg_stat_statements, pg_buffercache, pageinspect, pg_freespacemap, pg_visibility) - Using pg_basebackup to build replicas - Using pg_receivewal to have a WAL archive Of course, there's a lot of additional tutorials that would be nice to have which go beyond what's in core and leverage tools like pgbouncer, pgbackrest, patroni, etc, but they'd go on the wiki or elsewhere since they would be necessairly referring to bits that are outside of PG core. Thanks! Stephen
Вложения
On 07/20/2018 05: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. > > 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 > I trust you took notes of specific things user were seeking. Lay those out, here or else where, and see if anyone steps up to answer something specific. The majority of the audience here (me seriously not included) is NOT looking for how-tos. Generally given the chance on this list, members of that majority step in and provide very specific answers to specific questions (and sometime general notions are addressed as well). They, that majority, simply don't know what isn't obvious - until it isn't to someone.
On Friday, July 20, 2018, Joshua D. Drake <jd@commandprompt.com> wrote:
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.
People have chosen to solve this via books and writing applications that build onto the infrastructure PostgreSQL provides (in particular in the area of backups).
There is room for making others' lives easier in a more structured way but that takes time - which if you limit any acceptable solution to "free as in beer" is going to likely result in status quo (publish stuff however each person wishes and let people find it via search engine or as a result of asking questions on -general or SO.
We don't have to be everything to everyone and free to boot.
Writing up documentation and guides to answer specific questions that are posed and lack answers elsewhere (or in a desireable format) is something that will have a good chance to garner a concrete positive result. This thread, at this point and IMO, has served its purpose - to remind others that we have a possible gap in our accessibility. That goal seems largely accomplished and anyone wanting to discuss specific thoughts for addressing this please post an appropriately subject line message to -general with those concrete thoughts. Otherwise we now have a good feel for current reality and can find resources and then point people to those that exist today next time questions come up (or have them asked on -general).
David J.
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.klaver@aklaver.com
On 07/20/2018 04:56 PM, Stephen Frost wrote: > > +1. I'd personally like to see improvements to the tutorials, and > patches could certainly be submitted or specific ideas discussed over on > -docs. > > A few ideas around that would be: > > - Setting up async replication > - Setting up sync replication, with quorum-based sync > - Cascading replication > - Parallel pg_dump-based backup/restore (with pg_dumpall for globals) > - Using various important extensions (pg_stat_statements, > pg_buffercache, pageinspect, pg_freespacemap, pg_visibility) > - Using pg_basebackup to build replicas > - Using pg_receivewal to have a WAL archive I think this is a pretty good list. I would add: Practical Role management 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/20/2018 05:31 PM, Adrian Klaver wrote: > 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:) Hey it happens once every 18 months or so ;) 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 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@momjian.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 +
Hi
2018-08-10 21:00 GMT+02:00 Bruce Momjian <bruce@momjian.us>:
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.
I wrote lot of documentation related to plpgsql and some other, but unfortunately it is in Czech language. It is free, so it can be freely transalated
Here are links - on the page is a possibility to set google translator
Regards
Pavel
--
Bruce Momjian <bruce@momjian.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 +