pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedDirect links to edit documentation
9+ messages / 5 participants
[nested] [flat]
* Direct links to edit documentation
@ 2020-04-29 16:36 PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 9+ messages in thread
From: PG Doc comments form @ 2020-04-29 16:36 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: yuriastrakhan@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/runtime-config-wal.html
Description:
Would it be possible to add "edit this page" links to every PostgreSQL doc
page, pointing to the docs git repo, ideally on a site that allows
on-the-site editing without locally cloning i.e. github? This will make it
far easier to contribute tiny changes like adding more links in the text.
For example, https://www.postgresql.org/docs/12/runtime-config-wal.html has
a lot of useful information, but many setting keywords are not links, making
it harder to find. Commenting on that page that a link is missing seems
silly, whereas if there was an edit button, users could have submitted their
edits directly.
Thanks!
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Direct links to edit documentation
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
@ 2020-04-29 17:27 ` Bruce Momjian <bruce@momjian.us>
2020-04-29 21:34 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
0 siblings, 1 reply; 9+ messages in thread
From: Bruce Momjian @ 2020-04-29 17:27 UTC (permalink / raw)
To: yuriastrakhan@gmail.com; pgsql-docs@lists.postgresql.org
On Wed, Apr 29, 2020 at 04:36:37PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/runtime-config-wal.html
> Description:
>
> Would it be possible to add "edit this page" links to every PostgreSQL doc
> page, pointing to the docs git repo, ideally on a site that allows
> on-the-site editing without locally cloning i.e. github? This will make it
> far easier to contribute tiny changes like adding more links in the text.
> For example, https://www.postgresql.org/docs/12/runtime-config-wal.html has
> a lot of useful information, but many setting keywords are not links, making
> it harder to find. Commenting on that page that a link is missing seems
> silly, whereas if there was an edit button, users could have submitted their
> edits directly.
Wow, that sounds like a nice idea, but I have no idea how to do that.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Direct links to edit documentation
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
@ 2020-04-29 21:34 ` Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 17:06 ` Re: Direct links to edit documentation Magnus Hagander <magnus@hagander.net>
0 siblings, 1 reply; 9+ messages in thread
From: Yuri Astrakhan @ 2020-04-29 21:34 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs@lists.postgresql.org
ElasticSearch also uses AsciiDoc with the "edit_me" module that generates
those. Code -
https://github.com/elastic/docs/blob/master/resources/asciidoctor/lib/edit_me/extension.rb
It results in a semi-transparent "edit me" button at the top to the right
of the page title, e.g.
https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-geotilegr...
On Wed, Apr 29, 2020 at 1:27 PM Bruce Momjian <bruce@momjian.us> wrote:
> On Wed, Apr 29, 2020 at 04:36:37PM +0000, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/12/runtime-config-wal.html
> > Description:
> >
> > Would it be possible to add "edit this page" links to every PostgreSQL
> doc
> > page, pointing to the docs git repo, ideally on a site that allows
> > on-the-site editing without locally cloning i.e. github? This will make
> it
> > far easier to contribute tiny changes like adding more links in the
> text.
> > For example, https://www.postgresql.org/docs/12/runtime-config-wal.html
> has
> > a lot of useful information, but many setting keywords are not links,
> making
> > it harder to find. Commenting on that page that a link is missing seems
> > silly, whereas if there was an edit button, users could have submitted
> their
> > edits directly.
>
> Wow, that sounds like a nice idea, but I have no idea how to do that.
>
> --
> Bruce Momjian <bruce@momjian.us> https://momjian.us
> EnterpriseDB https://enterprisedb.com
>
> + As you are, so once was I. As I am, so you will be. +
> + Ancient Roman grave inscription +
>
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Direct links to edit documentation
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
2020-04-29 21:34 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
@ 2020-05-04 17:06 ` Magnus Hagander <magnus@hagander.net>
2020-05-04 19:23 ` Re: Direct links to edit documentation Daniel Gustafsson <daniel@yesql.se>
2020-05-05 14:49 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
0 siblings, 2 replies; 9+ messages in thread
From: Magnus Hagander @ 2020-05-04 17:06 UTC (permalink / raw)
To: Yuri Astrakhan <yuriastrakhan@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; Pg Docs <pgsql-docs@lists.postgresql.org>
I see how that can be pretty useful for something that's as simple as
asciidoc. But I wonder how useful it would be for our docbook documentation.
There'd be no preview (which there i sin the elastic), and we know how
difficult it can be to get the tags right without running test builds even
for those that are used to working in the system.
Though if what we're considering are basically drive-by typo fixes and
such, those would probably work in a scenario like that, since you're
unlikely to need a preview or break a build.
Another complication would be that we don't have a 1-1 mapping between
source files and output URLs. So you'd have to find some way to track it
back to the exactly right portion of the source file. This would probably
be possible if we were to do it as a feature on our own site (and not just
a source-edit-on-github-style), but it would probably ont be a trivial
piece of work. Question is if the benefit would outweigh the cost, compared
to just receiving comments and "manually patching them in".
//Magnus
On Wed, Apr 29, 2020 at 11:39 PM Yuri Astrakhan <yuriastrakhan@gmail.com>
wrote:
> ElasticSearch also uses AsciiDoc with the "edit_me" module that generates
> those. Code -
> https://github.com/elastic/docs/blob/master/resources/asciidoctor/lib/edit_me/extension.rb
>
> It results in a semi-transparent "edit me" button at the top to the right
> of the page title, e.g.
> https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-geotilegr...
>
> On Wed, Apr 29, 2020 at 1:27 PM Bruce Momjian <bruce@momjian.us> wrote:
>
>> On Wed, Apr 29, 2020 at 04:36:37PM +0000, PG Doc comments form wrote:
>> > The following documentation comment has been logged on the website:
>> >
>> > Page: https://www.postgresql.org/docs/12/runtime-config-wal.html
>> > Description:
>> >
>> > Would it be possible to add "edit this page" links to every PostgreSQL
>> doc
>> > page, pointing to the docs git repo, ideally on a site that allows
>> > on-the-site editing without locally cloning i.e. github? This will
>> make it
>> > far easier to contribute tiny changes like adding more links in the
>> text.
>> > For example, https://www.postgresql.org/docs/12/runtime-config-wal.html
>> has
>> > a lot of useful information, but many setting keywords are not links,
>> making
>> > it harder to find. Commenting on that page that a link is missing seems
>> > silly, whereas if there was an edit button, users could have submitted
>> their
>> > edits directly.
>>
>> Wow, that sounds like a nice idea, but I have no idea how to do that.
>>
>> --
>> Bruce Momjian <bruce@momjian.us> https://momjian.us
>> EnterpriseDB https://enterprisedb.com
>>
>> + As you are, so once was I. As I am, so you will be. +
>> + Ancient Roman grave inscription +
>>
>
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Direct links to edit documentation
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
2020-04-29 21:34 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 17:06 ` Re: Direct links to edit documentation Magnus Hagander <magnus@hagander.net>
@ 2020-05-04 19:23 ` Daniel Gustafsson <daniel@yesql.se>
2020-05-04 20:38 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 20:41 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
1 sibling, 2 replies; 9+ messages in thread
From: Daniel Gustafsson @ 2020-05-04 19:23 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; +Cc: Yuri Astrakhan <yuriastrakhan@gmail.com>; Bruce Momjian <bruce@momjian.us>; Pg Docs <pgsql-docs@lists.postgresql.org>
> On 4 May 2020, at 19:06, Magnus Hagander <magnus@hagander.net> wrote:
> Question is if the benefit would outweigh the cost, compared to just receiving
> comments and "manually patching them in".
Another question is the cost of managing access to such a system, we haven't
exactly had the best of luck with input from interactive systems in the past.
Is a community login enough or does it need an extra bit like the Wiki? Just
thinking out loud of the costs involved which need to be offset.
cheers ./daniel
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Direct links to edit documentation
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
2020-04-29 21:34 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 17:06 ` Re: Direct links to edit documentation Magnus Hagander <magnus@hagander.net>
2020-05-04 19:23 ` Re: Direct links to edit documentation Daniel Gustafsson <daniel@yesql.se>
@ 2020-05-04 20:38 ` Yuri Astrakhan <yuriastrakhan@gmail.com>
1 sibling, 0 replies; 9+ messages in thread
From: Yuri Astrakhan @ 2020-05-04 20:38 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Magnus Hagander <magnus@hagander.net>; Bruce Momjian <bruce@momjian.us>; Pg Docs <pgsql-docs@lists.postgresql.org>
Daniel and Magnus, thanks for your replies. Here's my personal 2-click
submission "ideal scenario", that may differ from other contributors, but
seems to be very common now for many FOSS projects. I think this will work
for the vast majority of the documentation pages. Note that this is not a
wiki-style editing, but a proper pull request process subject to
maintainer's review.
* While viewing the "CREATE TABLE" page [1], I click some "edit" button
(e.g. in the upper right corner)
* It takes me to the GitHub "edit" page [2] (this is the link target of the
gray pencil icon on page [3] - upper right corner on gray background)
* I edit the page -- the syntax seems trivial enough for the vast majority
of non-structural edits. I can add more examples, improve grammar, add
links, etc.
* I click "Propose file changes" at the bottom. This automatically will
create a fork of the repo, and create a pull request into the main Postgres
github repo.
* (automated step) some bot creates a PR against the primary Postgres
repo, submitting the change.
* Maintainers review and merge the change.
Now, I do see that https://github.com/postgres/postgres is not the primary
repo, and that currently PRs to it do not go to the maintainers, but I
think it would greatly simplify the path of user contributions if GitHub
PRs were auto-submitted using the proper Postgres process (i.e. with a
bot?). Just compare the above 2 clicks process to submit a documentation
change with the giant instruction page at
https://wiki.postgresql.org/wiki/Submitting_a_Patch -- clearly it is a big
deterrent for small improvements.
On Mon, May 4, 2020 at 3:23 PM Daniel Gustafsson <daniel@yesql.se> wrote:
> > On 4 May 2020, at 19:06, Magnus Hagander <magnus@hagander.net> wrote:
>
> > Question is if the benefit would outweigh the cost, compared to just
> receiving
> > comments and "manually patching them in".
>
> Another question is the cost of managing access to such a system, we
> haven't
> exactly had the best of luck with input from interactive systems in the
> past.
> Is a community login enough or does it need an extra bit like the Wiki?
> Just
> thinking out loud of the costs involved which need to be offset.
>
> cheers ./daniel
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Direct links to edit documentation
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
2020-04-29 21:34 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 17:06 ` Re: Direct links to edit documentation Magnus Hagander <magnus@hagander.net>
2020-05-04 19:23 ` Re: Direct links to edit documentation Daniel Gustafsson <daniel@yesql.se>
@ 2020-05-04 20:41 ` Yuri Astrakhan <yuriastrakhan@gmail.com>
1 sibling, 0 replies; 9+ messages in thread
From: Yuri Astrakhan @ 2020-05-04 20:41 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Magnus Hagander <magnus@hagander.net>; Bruce Momjian <bruce@momjian.us>; Pg Docs <pgsql-docs@lists.postgresql.org>
(accidentally sent my last post without the links at the bottom, fixed)
Daniel and Magnus, thanks for your replies. Here's my personal 2-click
submission "ideal scenario", that may differ from other contributors, but
seems to be very common now for many FOSS projects. I think this will work
for the vast majority of the documentation pages. Note that this is not a
wiki-style editing, but a proper pull request process subject to
maintainer's review.
* While viewing the "CREATE TABLE" page [1], I click some "edit" button
(e.g. in the upper right corner)
* It takes me to the GitHub "edit" page [2] (this is the link target of the
gray pencil icon on page [3] - upper right corner on gray background)
* I edit the page -- the syntax seems trivial enough for the vast majority
of non-structural edits. I can add more examples, improve grammar, add
links, etc.
* I click "Propose file changes" at the bottom. This automatically will
create a fork of the repo, and create a pull request into the main Postgres
github repo.
* (automated step) some bot creates a PR against the primary Postgres
repo, submitting the change.
* Maintainers review and merge the change.
Now, I do see that https://github.com/postgres/postgres is not the primary
repo, and that currently PRs to it do not go to the maintainers, but I
think it would greatly simplify the path of user contributions if GitHub
PRs were auto-submitted using the proper Postgres process (i.e. with a
bot?). Just compare the above 2 clicks process to submit a documentation
change with the giant instruction page at
https://wiki.postgresql.org/wiki/Submitting_a_Patch -- clearly it is a big
deterrent for small improvements.
[1] https://www.postgresql.org/docs/current/sql-createtable.html
[2]
https://github.com/postgres/postgres/edit/master/doc/src/sgml/ref/create_table.sgml
[3]
https://github.com/postgres/postgres/blob/master/doc/src/sgml/ref/create_table.sgml
On Mon, May 4, 2020 at 3:23 PM Daniel Gustafsson <daniel@yesql.se> wrote:
> > On 4 May 2020, at 19:06, Magnus Hagander <magnus@hagander.net> wrote:
>
> > Question is if the benefit would outweigh the cost, compared to just
> receiving
> > comments and "manually patching them in".
>
> Another question is the cost of managing access to such a system, we
> haven't
> exactly had the best of luck with input from interactive systems in the
> past.
> Is a community login enough or does it need an extra bit like the Wiki?
> Just
> thinking out loud of the costs involved which need to be offset.
>
> cheers ./daniel
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Direct links to edit documentation
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
2020-04-29 21:34 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 17:06 ` Re: Direct links to edit documentation Magnus Hagander <magnus@hagander.net>
@ 2020-05-05 14:49 ` Bruce Momjian <bruce@momjian.us>
2020-05-06 15:04 ` Re: Direct links to edit documentation Magnus Hagander <magnus@hagander.net>
1 sibling, 1 reply; 9+ messages in thread
From: Bruce Momjian @ 2020-05-05 14:49 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; +Cc: Yuri Astrakhan <yuriastrakhan@gmail.com>; Pg Docs <pgsql-docs@lists.postgresql.org>
On Mon, May 4, 2020 at 07:06:55PM +0200, Magnus Hagander wrote:
> I see how that can be pretty useful for something that's as simple as asciidoc.
> But I wonder how useful it would be for our docbook documentation.
>
> There'd be no preview (which there i sin the elastic), and we know how
> difficult it can be to get the tags right without running test builds even for
> those that are used to working in the system.
>
> Though if what we're considering are basically drive-by typo fixes and such,
> those would probably work in a scenario like that, since you're unlikely to
> need a preview or break a build.
>
> Another complication would be that we don't have a 1-1 mapping between source
> files and output URLs. So you'd have to find some way to track it back to the
> exactly right portion of the source file. This would probably be possible if we
> were to do it as a feature on our own site (and not just a
> source-edit-on-github-style), but it would probably ont be a trivial piece of
> work. Question is if the benefit would outweigh the cost, compared to just
> receiving comments and "manually patching them in".
All I can say is that most emails we get about the docs using the form
are just complaints, and we have to write some suggested text and get
approaval from the reporter that the text is clear. We don't get many
acutal _suggestions_.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Direct links to edit documentation
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
2020-04-29 21:34 ` Re: Direct links to edit documentation Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 17:06 ` Re: Direct links to edit documentation Magnus Hagander <magnus@hagander.net>
2020-05-05 14:49 ` Re: Direct links to edit documentation Bruce Momjian <bruce@momjian.us>
@ 2020-05-06 15:04 ` Magnus Hagander <magnus@hagander.net>
0 siblings, 0 replies; 9+ messages in thread
From: Magnus Hagander @ 2020-05-06 15:04 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Yuri Astrakhan <yuriastrakhan@gmail.com>; Pg Docs <pgsql-docs@lists.postgresql.org>
On Tue, May 5, 2020 at 4:49 PM Bruce Momjian <bruce@momjian.us> wrote:
> On Mon, May 4, 2020 at 07:06:55PM +0200, Magnus Hagander wrote:
> > I see how that can be pretty useful for something that's as simple as
> asciidoc.
> > But I wonder how useful it would be for our docbook documentation.
> >
> > There'd be no preview (which there i sin the elastic), and we know how
> > difficult it can be to get the tags right without running test builds
> even for
> > those that are used to working in the system.
> >
> > Though if what we're considering are basically drive-by typo fixes and
> such,
> > those would probably work in a scenario like that, since you're unlikely
> to
> > need a preview or break a build.
> >
> > Another complication would be that we don't have a 1-1 mapping between
> source
> > files and output URLs. So you'd have to find some way to track it back
> to the
> > exactly right portion of the source file. This would probably be
> possible if we
> > were to do it as a feature on our own site (and not just a
> > source-edit-on-github-style), but it would probably ont be a trivial
> piece of
> > work. Question is if the benefit would outweigh the cost, compared to
> just
> > receiving comments and "manually patching them in".
>
> All I can say is that most emails we get about the docs using the form
> are just complaints, and we have to write some suggested text and get
> approaval from the reporter that the text is clear. We don't get many
> acutal _suggestions_.
>
Agreed. I think the argument made is that if we had direct editing, maybe
we'd get more actual suggestions vs just reports/complaints.
--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/;
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2020-05-06 15:04 UTC | newest]
Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-04-29 16:36 Direct links to edit documentation PG Doc comments form <noreply@postgresql.org>
2020-04-29 17:27 ` Bruce Momjian <bruce@momjian.us>
2020-04-29 21:34 ` Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 17:06 ` Magnus Hagander <magnus@hagander.net>
2020-05-04 19:23 ` Daniel Gustafsson <daniel@yesql.se>
2020-05-04 20:38 ` Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-04 20:41 ` Yuri Astrakhan <yuriastrakhan@gmail.com>
2020-05-05 14:49 ` Bruce Momjian <bruce@momjian.us>
2020-05-06 15:04 ` Magnus Hagander <magnus@hagander.net>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox