Content-Type: text/plain;
	charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3696.120.41.1.4\))
Subject: Re: An improved README experience for PostgreSQL
From: Daniel Gustafsson <daniel@yesql.se>
In-Reply-To: <20240228170237.GB2435539@nathanxps13>
Date: Wed, 28 Feb 2024 18:25:32 +0100
Cc: Tom Lane <tgl@sss.pgh.pa.us>,
 Andrew Atkinson <andyatkinson@gmail.com>,
 PostgreSQL Hackers <pgsql-hackers@postgresql.org>,
 samay@tembo.io
Content-Transfer-Encoding: quoted-printable
Message-Id: <B0AA4094-A8D2-441A-AC31-6B4AD91E93C0@yesql.se>
References: <CAG6XLEmGE95DdKqjk+Dd9vC8mfN7BnV2WFgYk_9ovW6ikN0YSg@mail.gmail.com>
 <20240226183018.GA2109010@nathanxps13> <1967819.1708979436@sss.pgh.pa.us>
 <DAB16F23-BE05-44E3-80DB-8D60961B8906@yesql.se>
 <20240228170237.GB2435539@nathanxps13>
To: Nathan Bossart <nathandbossart@gmail.com>
Archived-At: <https://www.postgresql.org/message-id/B0AA4094-A8D2-441A-AC31-6B4AD91E93C0%40yesql.se>
Precedence: bulk

> On 28 Feb 2024, at 18:02, Nathan Bossart <nathandbossart@gmail.com> =
wrote:
>=20
> On Wed, Feb 28, 2024 at 02:46:11PM +0100, Daniel Gustafsson wrote:
>>> On 26 Feb 2024, at 21:30, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>> Nathan Bossart <nathandbossart@gmail.com> 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.
>>>=20
>>> 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.
>>=20
>> 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.
>=20
> 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.

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