3 ms·

Oh boy it's been a while since I've read something I disagree with to this extent! People use Markdown because you can read it both in its formatted version an

by untog 7y ago

Oh boy it's been a while since I've read something I disagree with to this extent! People use Markdown because you can read it both in its formatted version and in its raw unformatted source. Asciidoc is... not that. Just looking at the examples it looks like a full templating language: conditionals, includes, blocks... I don't want any of this. > Actually, I was surprised by the fact that so many people think Markdown is a really powerful tool for documentation. I don't think Markdown is powerful, unless you're counting "power through simplicity". Markdown's lack of power is a positive: there is a very limited set of things I need to learn in order to use it effectively and someone who knows literally nothing about Markdown can read its source immediately.

Symbiote 7y ago
I don't see how AsciiDoc source is any more or less readable than Markdown. AsciiDoc does everything Markdown does, but since there's a specification there are no inconsistencies. It also has features beyond that. You don't need to use them. Edit: here's an example from KiCAD's documentation ("Raw" to view the source, as GitHub supports AsciiDoc as well as Markdown) https://github.com/KiCad/kicad-doc/blob/master/src/getting_started_in_kicad/getting_started_in_kicad.adoc https://github.com/KiCad/kicad-doc/blob/master/src/getting_s...
- jmilloy 7y ago
  > You don't need to use them. You do if you are reading a source that uses them.
- dwohnitmok 7y ago
  The argument that certain features are optional overlooks the fact that other people can and will use them, especially in collaborative projects. That's not a death knell. You can gate the features behind style guides, linters, or social conventions. However, those are costs in and of themselves. Additional features of a language always have a carrying cost, even behind optional flags.
- untog 7y ago
  > You don't need to use them. But people will, though. If you're lucky enough to be there at the start of project you could establish a list of allowed functionality but at that point you're documenting your documentation, which feels, uh, sub optimal.
bjourne 7y ago
Here's a full AsciiDoc example: http://asciidoc.org/asciidoc.txt http://asciidoc.org/asciidoc.txt I get that you prefer Markdown but AsciiDoc isn't a very complicated format.

by untog 7y ago

Symbiote 7y ago

I don't see how AsciiDoc source is any more or less readable than Markdown. AsciiDoc does everything Markdown does, but since there's a specification there are no inconsistencies. It also has features beyond that. You don't need to use them. Edit: here's an example from KiCAD's documentation ("Raw" to view the source, as GitHub supports AsciiDoc as well as Markdown) https://github.com/KiCad/kicad-doc/blob/master/src/getting_started_in_kicad/getting_started_in_kicad.adoc https://github.com/KiCad/kicad-doc/blob/master/src/getting_s...

jmilloy 7y ago
> You don't need to use them. You do if you are reading a source that uses them.
dwohnitmok 7y ago
The argument that certain features are optional overlooks the fact that other people can and will use them, especially in collaborative projects. That's not a death knell. You can gate the features behind style guides, linters, or social conventions. However, those are costs in and of themselves. Additional features of a language always have a carrying cost, even behind optional flags.
untog 7y ago
> You don't need to use them. But people will, though. If you're lucky enough to be there at the start of project you could establish a list of allowed functionality but at that point you're documenting your documentation, which feels, uh, sub optimal.

bjourne 7y ago

Here's a full AsciiDoc example: http://asciidoc.org/asciidoc.txt http://asciidoc.org/asciidoc.txt I get that you prefer Markdown but AsciiDoc isn't a very complicated format.