Subject: Re: An improved README experience for PostgreSQL

From: Nathan Bossart <[email-masked]>
Date: Wed, 28 Feb 2024 11:02:37 -0600

On Wed, Feb 28, 2024 at 02:46:11PM +0100, Daniel Gustafsson wrote:
>> On 26 Feb 2024, at 21:30, Tom Lane <[email-masked]> wrote:
>> Nathan Bossart <[email-masked]> writes:
>>> I think this would be nice.  If the Markdown version is reasonably readable
>>> as plain-text, maybe we could avoid maintaining two READMEs files, too.
>>> But overall, +1 to modernizing the README a bit.
>> 
>> Per past track record, we change the top-level README only once every
>> three years or so, so I doubt it'd be too painful to maintain two
>> versions of it.
> 
> It wont be, and we kind of already have two since there is another similar
> README displayed at https://www.postgresql.org/ftp/.  That being said, a
> majority of those reading the README will likely be new developers accustomed
> to Markdown (or doing so via interfaces such as Github) so going to Markdown
> might not be a bad idea.  We can also render a plain text version with pandoc
> for release builds should we want to.

Sorry, my suggestion wasn't meant to imply that I have any strong concerns
about maintaining two README files.  If we can automate generating one or
the other, that'd be great, but I don't see that as a prerequisite to
adding a Markdown version.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

---

From: Tom Lane <[email-masked]>
Date: Wed, 28 Feb 2024 12:17:04 -0500

> adding a Markdown version.

Agreed, and I'd go so far as to say that adding automation now
would be investing work that might well go to waste.  When and
if we get annoyed by the manual labor involved in maintaining
two copies, it'd be time to put work into automating it.

			regards, tom lane

---

From: Daniel Gustafsson <[email-masked]>
Date: Wed, 28 Feb 2024 18:25:32 +0100

> On 28 Feb 2024, at 18:02, Nathan Bossart <[email-masked]> wrote:
> 

Agreed, and I didn't say we should do it but rather that we can do it based on
the toolchain we already have.  Personally I think just having a Markdown
version is enough, it's become the de facto standard for such documentation for
good reasons.

--
Daniel Gustafsson

---

From: Joe Conway <[email-masked]>
Date: Wed, 28 Feb 2024 12:43:24 -0500

> version is enough, it's become the de facto standard for such documentation for

+1

Markdown is pretty readable as text, I'm not sure why we need both.

-- 
Joe Conway
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com