Re: Converting README documentation to Markdown

On 15.05.24 14:26, Daniel Gustafsson wrote:
> Another aspect of platform/flavour was to make the markdown version easy to
> maintain for hackers writing content. Requiring the minimum amount of markup
> seems like the developer-friendly way here to keep productivity as well as
> document quality high.
>
> Most importantly though, I targeted reading the files as plain text without any
> rendering. We keep these files in text format close to the code for a reason,
> and maintaining readability as text was a north star.

I've been thinking about this some more. I think the most value here
would be to just improve the plain-text formatting, so that there are
consistent list styles, header styles, indentation, some of the
ambiguities cleared up -- much of which your 0001 patch does. You might
as well be targeting markdown-like conventions with this; they are
mostly reasonable.

I tend to think that actually converting all the README files to
README.md could be a net negative for maintainability. Because now you
are requiring everyone who potentially wants to edit those to be aware
of Markdown syntax and manually check the rendering. With things like
DocBook, if you make a mess, you get error messages from the build step.
If you make a mess in Markdown, you have to visually find it yourself.
There are many READMEs that contain nested lists and code snippets and
diagrams and such all mixed together. Getting that right in Markdown
can be quite tricky. I'm also foreseeing related messes of trailing
whitespace, spaces-vs-tab confusion, gitattributes violations, etc. It
can be a lot of effort. It's okay to do this for prominent files like
the top-level one, but I suggest that for the rest we can keep it simple
and just use plain text.