> 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.g.johns...@gmail.com> wrote: > On Tue, Jan 18, 2022 at 4:01 PM Eric Mutta <eric.mu...@gmail.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. > >
