Re: An improved README experience for PostgreSQL

From: Andrew Atkinson <andyatkinson(at)gmail(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: Nathan Bossart <nathandbossart(at)gmail(dot)com>, "David E(dot) Wheeler" <david(at)justatheory(dot)com>, Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org>, Joe Conway <mail(at)joeconway(dot)com>, Daniel Gustafsson <daniel(at)yesql(dot)se>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>, Samay Sharma <samay(at)tembo(dot)io>
Subject: Re: An improved README experience for PostgreSQL
Date: 2024-02-28 20:07:34
Message-ID: CAG6XLE=tDjXQN0QzpcqU4DOy0odiLQKF0ANx3GC8k-+tKAU0PA@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

I've grabbed Nathan's patch, and pushed it to GitHub simply to preview the
rendered Markdown there. This isn't intended to be reviewed, this is just
for anyone else that's interested in easily seeing the HTML version of the
Markdown file compared with the earlier one.

Nathan's direct conversion:
https://github.com/postgres/postgres/blob/9c0f1dd350ee29ad3ade2816c4338b7ca5186bba/README.md

Original email version with more sections and content:
https://github.com/andyatkinson/postgres/blob/e88138765750b6f7898089b4016641eee01bf616/README.md

I agree that starting with the direct conversion is reasonable. Markdown
"modernizes" the file using a popular plain text file format that's
renderable.

However, I also think it would be cool to get some input on what the most
useful 2-3 content items are for new developers and make any additions
possible there. In writing this, I had an idea to ask about whether this
topic could be covered as an upcoming PostgreSQL community blog post
series. In theory, we could gather a variety of perspectives that way. That
could make it less subjective if we see several people independently
suggesting a particular wiki page for example, for inclusion in the README.
I'll pursue that outside the mailing list and report back!

On Wed, Feb 28, 2024 at 1:36 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Nathan Bossart <nathandbossart(at)gmail(dot)com> writes:
> > On Wed, Feb 28, 2024 at 01:08:03PM -0600, Nathan Bossart wrote:
> >> -PostgreSQL Database Management System
> >> -=====================================
> >> +# PostgreSQL Database Management System
>
> > This change can be omitted, which makes the conversion even simpler.
>
> That's a pretty convincing proof-of-concept. Let's just do this,
> and then make sure to keep the file legible as plain text.
>
> regards, tom lane
>

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Daniel Gustafsson 2024-02-28 20:13:56 Re: An improved README experience for PostgreSQL
Previous Message Melanie Plageman 2024-02-28 20:06:08 Re: BitmapHeapScan streaming read user and prelim refactoring