Re: Typo in "27.2.8. Synchronous Replication"

> While I appreciate we could be even more cool if we used a more modern
set of features, the effort it would take to do so doesn't seem to match
the benefit we would get. Our documentation is, on the whole, a strength.

Many thanks David, for the clarification on how the documentation release
process works. I definitely agree that the Postgres docs are one of its
greatest strength (every time I found myself saying "wow, Postgres is
amazing!" it was when I was reading the docs, long before I even opened
psql). Thanks to all of you who devote your time and energy to the docs -
they really make a difference to those of us coming from other (commerical)
databases!

On Wed, Jan 19, 2022, 02:28 David G. Johnston <david(dot)g(dot)johnston(at)gmail(dot)com>
wrote:

> On Tue, Jan 18, 2022 at 4:01 PM Eric Mutta <eric(dot)mutta(at)gmail(dot)com> wrote:
>
>>
>> 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.
>>
>
> I suspect a large part of your expectation is based upon this and that
> GitHub can display processed markdown natively. That is a huge difference
> between the experience you describe here and our SGML-based documentation.
>
>
>> 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.
>>
>
> Honestly, if this part works well (and even the immediate single-page
> editing), a functioning demonstration on a fork of our repo on GitHub would
> go a long way. Even if that fork is only used to get to the point of
> producing a pull request which the coder can then copy and paste into an
> email message to -hackers to be formally applied to the codebase,
> back-patched if necessary (we don't make authors worry about back-patching).
>
> 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.
>>
>
> Having both the PR and the mailing list be places where code reviews might
> happen would be a concern - but the author can deal with that.
>
>
>> 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.
>>
>
> The desire to avoid entanglements on third-party services is a point made
> by comitters that is impossible to avoid if leveraging GitHub. And the
> barriers are much higher if we host our own (e.g., GitLab). But again,
> people who only know how to compile PostgreSQL (a low bar to meet) and are
> familiar with this ecosystem (a prerequisite if going down this path) can
> experiment and proof-of-concept.
>
> FYI, there is some current work being done to use Meson in the build
> process (I haven't kept up with the details).
>
>
>> (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).
>>
>
> The docs and the source code are maintained in the same manner. Once
> release 12.10 is published the v12 website and the source code will update
> to that latest version. That is arguably a policy decision that any new
> tooling would continue to adhere to. You can check that the current HEAD
> has the patch because we do publish a development branch for that.
>
> In short, the committers tend to get trivial fixes to the docs applied
> without any difficulty or delay, even when presented with just a url link
> and some suggestion text. The sgml overhead on those is minimal. While I
> appreciate we could be even more cool if we used a more modern set of
> features, the effort it would take to do so doesn't seem to match the
> benefit we would get. Our documentation is, on the whole, a strength.
>
> David J.
>
>