On Thursday, 1 February 2018 at 03:00:07 UTC, Walter Bright wrote:
On 1/31/2018 5:58 PM, H. S. Teoh wrote:
cosmetic features.
I tough lesson I've learned is that cosmetics matter, a lot.
Sometimes much more than substance. There's no getting away
from it.
This is one reason I recommend markdown for docs. Cosmetics is
what markdown does best. People *like* looking at it and editing
it. It's like typing an email or a forum comment.
Other reasons I recommend it are:
* everyone already knows it (it's at github, stackoverflow, and
reddit),
* it's fairly easy to write (as easy as possible while still
looking good),
* there's an open spec (CommonMark), and
* writing new language-specific markup formats appears to be
something that's not done anymore. There's javadoc, texinfo,
doxygen, docbook, groff --- all very ... *mature* technologies.
In modern projects: Rust uses markdown, Python uses reST, Git
uses asciidoc --- all general-purpose non- language-specific
lightweight markup formats.
The only reason I can think of for *not* using markdown for
project docs is if your project is another competing lightweight
markup format.
