Re: Direct links to edit documentation

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(at)gmail(dot)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-geotilegrid-aggregation.html
>
> On Wed, Apr 29, 2020 at 1:27 PM Bruce Momjian <bruce(at)momjian(dot)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(at)momjian(dot)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 +
>>
>