It sounds like restructuredText and Asciidoc are the top choices. They both look capable:

I can, as a next step, post this as an Issue on the Github project and it can be triaged and tracked.

For something like this, it might even make sense to create a new branch so that multiple people can work on it. In that case, splitting the documentation into multiple files would be helpful too. If approved, an empty file for each section of the documentation could be created in order to have the skeleton of the project. Having the documentation split into multiple files may make maintaining the documentation easier in the future too (i.e. someone could change one section without conflicting with a person making a change in another section).

How have collaborative efforts like this been done in the past? How would multiple people be able to commit changes to this branch?

Other thoughts?

------ Original Message ------
From: "Pavlos Parissis" <>
To: "Nick Ramirez" <>
Sent: 7/3/2019 10:44:11 AM
Subject: Re: The case for changing the documentation syntax

On Δευτέρα, 1 Ιουλίου 2019 5:01:33 Μ.Μ. CEST Nick Ramirez wrote:
 Hello all,


 The solution I am proposing:

 Rather than using a home-grown, difficult to parse,
 not-consistently-used grammar. We should use a standard. We should use

 The reStructuredText syntax gives us the following benefits:

 * It is well documented
 * Tools exist to parse this and convert it to other formats (such as
 * Tools exist that will "error check" the document to ensure that the
 correct syntax is used throughout configuration.txt (which would become
 * Tools such as Jekyll can easily parse reStructuredText and build
 sophisticated, beautiful webpages that feature search functionality,
 table-of-contents, images, graphs, links, etc. We could really start to
 make the documentation shine!
 * We won't have to worry about updating special tools because
 reStructuredText syntax will allow us to reliably parse it forever
 * reStructuredText is still easily human-readable using a terminal,
 plain-text editor, etc.

 I and others are fully willing to make the conversion to
 reStructuredText, too. What do you all think?

+1 from me. asciidoctor is something you should have a look at and consider as 
I know that people don't like markdown, but it is very simple to use and that 
is, sometimes, more
important than standards and etc.

My cents,

Reply via email to