5 ms·

This reminds me of a comment on an anti-markdown post I read a few years back. "As far as I'm concerned the best tool for writing documentation is the one that

This reminds me of a comment on an anti-markdown post I read a few years back. "As far as I'm concerned the best tool for writing documentation is the one that anyone can actually be bothered to use. Markdown might not be perfect but at least it's simple and commonly understood so there isn't much barrier to writing/updating documentation." - warmans [1] https://www.reddit.com/r/programming/comments/4ck2lu/why_you_shouldnt_use_markdown_for_documentation/ https://www.reddit.com/r/programming/comments/4ck2lu/why_you...

bhaak 7y ago
Then you still need somebody who cleans up the documentation afterwards or converts it into your Markdown dialect of choice. If you have such a person anyway, you can just let other contributors write simple text without any styling to begin with.
- pen2l 7y ago
  1) Due to natural inertia there exists to leave things alone that aren’t overtly broken, I doubt there would be a lot of cases in which people would feel so inclined to convert to a different format 2) If people do need to convert it, at least it’s a simple enough spec that conversion shouldn’t require a Herculean amount of effort (I bet there already exist converters that others have written)
  - bhaak 7y ago
    As Markdown is available in a plethora of dialects, it's likely any given converter doesn't work 100% correct with the dialect at hand. Granted, that's only a weak argument against Markdown. I rarely encountered converters that would work 100% correct for any given textual format.
Aardwolf 7y ago
My biggest gripe with markdown for writing is its removal of single intentional newlines.
- antipaul 7y ago
  I think you can achieve that with 2 spaces at the end
  - Aardwolf 7y ago
    Yes, but, my gripe is how markdown breaks standard plain text behavior, without requiring extra formatting (those two spaces). They should have required the extra formatting for the opposite case, if you want to break a line in your code for some reason but not in the final result. Confusingly those two spaces also don't work in hacker news comments while some other markdown features do. If it was like plain text, with a few ascii symbols used for formatting (like *, _, ...), it'd have been more fantastic than now. BBCode is better imho.
    - tobylane 7y ago
      The backslash\ may qualify, and it’s part of the standard.
    - jachee 7y ago
      > while some other markdown features do. The only two markdown features afaik that work on HN are italics with asterisks and code blocks with 4 spaces. That's it.
  - ilammy 7y ago
    > 2 spaces at the end I prefer just plain "<br/>" because it does not mess with my editor configuration, which otherwise I have to constantly tweak between "strip all whitespace at the end of line" and back.
- dbalatero 7y ago
  I like it, as it lets me format at 80-char breaks to prevent infinite line lengths for paragraphs of text. This makes Github diffs easier to read as well.
  - khc 7y ago
Groxx 7y ago
To pile on a +1 for this: I've seen a huge increase in basic documentation after switching from RST to MD. 5x or more. Highly-crafted docs are indeed better in RST (or some other rich system), but it's also a huge turn-off for random contributors due to its unfamiliarity and verbosity.
mastermojo 7y ago
Agreed! Every time I need to do something in markdown I just pull up a cheatsheet and start typing. It's so simple that it fits on a page and I don't even feel like I have to learn it to use it. Markdown works for github README.md. It works in Trello. I have it on my blog that I update once a decade. I don't find the argument to stop using it persuasive at all.

bhaak 7y ago

Then you still need somebody who cleans up the documentation afterwards or converts it into your Markdown dialect of choice. If you have such a person anyway, you can just let other contributors write simple text without any styling to begin with.

pen2l 7y ago
1) Due to natural inertia there exists to leave things alone that aren’t overtly broken, I doubt there would be a lot of cases in which people would feel so inclined to convert to a different format 2) If people do need to convert it, at least it’s a simple enough spec that conversion shouldn’t require a Herculean amount of effort (I bet there already exist converters that others have written)
- bhaak 7y ago
  As Markdown is available in a plethora of dialects, it's likely any given converter doesn't work 100% correct with the dialect at hand. Granted, that's only a weak argument against Markdown. I rarely encountered converters that would work 100% correct for any given textual format.

Aardwolf 7y ago

My biggest gripe with markdown for writing is its removal of single intentional newlines.

antipaul 7y ago
I think you can achieve that with 2 spaces at the end
- Aardwolf 7y ago
  Yes, but, my gripe is how markdown breaks standard plain text behavior, without requiring extra formatting (those two spaces). They should have required the extra formatting for the opposite case, if you want to break a line in your code for some reason but not in the final result. Confusingly those two spaces also don't work in hacker news comments while some other markdown features do. If it was like plain text, with a few ascii symbols used for formatting (like *, _, ...), it'd have been more fantastic than now. BBCode is better imho.
  - tobylane 7y ago
    The backslash\ may qualify, and it’s part of the standard.
  - jachee 7y ago
    > while some other markdown features do. The only two markdown features afaik that work on HN are italics with asterisks and code blocks with 4 spaces. That's it.
- ilammy 7y ago
  > 2 spaces at the end I prefer just plain "<br/>" because it does not mess with my editor configuration, which otherwise I have to constantly tweak between "strip all whitespace at the end of line" and back.
dbalatero 7y ago
I like it, as it lets me format at 80-char breaks to prevent infinite line lengths for paragraphs of text. This makes Github diffs easier to read as well.
- khc 7y ago

Groxx 7y ago

To pile on a +1 for this: I've seen a huge increase in basic documentation after switching from RST to MD. 5x or more. Highly-crafted docs are indeed better in RST (or some other rich system), but it's also a huge turn-off for random contributors due to its unfamiliarity and verbosity.

mastermojo 7y ago

Agreed! Every time I need to do something in markdown I just pull up a cheatsheet and start typing. It's so simple that it fits on a page and I don't even feel like I have to learn it to use it. Markdown works for github README.md. It works in Trello. I have it on my blog that I update once a decade. I don't find the argument to stop using it persuasive at all.