Re: Typo in "27.2.8. Synchronous Replication"

Hi Magnus,

You are correct that doing a Pull Request would involve more overhead in
terms of checking out code, doing builds, etc, however GitHub automates
much of that and it all runs in the cloud so you can do it in a browser on
your phone while on the train if you wanted to. It literally takes a few
clicks from start to finish. Here's the flow from a real example:

1. There was a typo in the "Restore and Recovery Overview (SQL Server)"
docs here
https://docs.microsoft.com/en-us/sql/relational-databases/backup-restore/restore-and-recovery-overview-sql-server?view=sql-server-ver15

2. I noticed the typo and on the top right of the page there's an "edit"
link. Click that and it takes you to GitHub where the Markdown text is.
GitHub automatically creates a fork of the repo for me and opens an editor
where I can edit the Markdown, get a diff so I can review the changes, then
commit with a message.

3. After committing, GitHub shows a "Create Pull Request" button. Click
that and it automatically copies the commit message, opens an editor that
allows me to edit further if needed. For simple typos you usually just
submit the PR, which I did here
https://github.com/MicrosoftDocs/sql-docs/pull/6840

4. When a PR is submitted, one or more actions run automatically to check
for merge conflicts, to run any build steps, tests, etc. Note: up to this
point, nobody on the docs team has been involved: it's just me and the
automated processes on GitHub.

5. If the automated actions complete successfully THEN the responsible
person is notified. They can review the PR and merge it with one click.
GitHub also makes it super simple to discuss the edits, make further
commits, etc if the PR has issues. A complete history is made visible right
there in the browser.

The SQL Server Docs Team also has an automated process to push changes to
the live site, usually in a matter of hours and the really nice touch is
that once the changes are live, the committer is credited on the live site
with their GitHub avatar and name (e.g. for that fix, you can see mine
here:
https://docs.microsoft.com/en-us/sql/relational-databases/backup-restore/restore-and-recovery-overview-sql-server?view=sql-server-ver15
- it's the third avatar from the left with name ericmutta).

Postgres existed long before GitHub and long before the CI/CD development
flow (which GitHub makes really easy) became mainstream, so it may take
some time and effort to adopt it. I do think the time will be well spent
because it will allow the already great Postgres docs to get even better
and do so FASTER (note that you pushed the fix on 27/Dec last year but over
three weeks later, the live site here
https://www.postgresql.org/docs/14/warm-standby.html still doesn't reflect
the fix).

Hopefully that provides food for thought, and I will be happy to
contribute/help further in any way I can.

Many thanks,
Eric.

On Sun, Jan 16, 2022 at 8:31 PM Magnus Hagander <magnus(at)hagander(dot)net> wrote:

> On Mon, Jan 3, 2022 at 1:40 PM Eric Mutta <eric(dot)mutta(at)gmail(dot)com> wrote:
> >
> > Hi Magnus, happy new year! Thanks for pushing the fix.
> >
> > Coming from an SQL Server background where the docs are hosted on GitHub
> and minor changes like this can be made by simply submitting a pull
> request, I am wondering is there anything similar for the Postgres docs?
> >
> > Going through a mailing list just to fix a typo feels like a lot of
> overhead!
>
> Hi!
>
> Personally, I would find sending an email to a mailing list or like
> you did, filling out the form on the website, would be *less* overhead
> than having to do a Pull Request (which would include checkout,
> verifying builds etc, no?).
>
> Can you enlighten me on exactly which part of the flow of that you
> think would make it easier? Perhaps it's something we can adopt
> something out of to make it easier for us as well. But I wonder if it
> more has to do with the structure of the docs than the actual tool?
> (That is, the error is on warm-standby.html, but the source is
> actually in a file called high-availability.sgml)
>
> //Magnus
>