Hacker News Reader

Comment by husarcik | Hacker News Reader

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...

View on HN

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.

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

I think you can achieve that with 2 spaces at the end

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.

The backslash\ may qualify, and it’s part of the standard.

> 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.

> 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.

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.

except when you add one word and re-flow the entire paragraph

Your editor should be able to help with that. For example in vim: `gqap` will reflow the current paragraph, or while in visual select mode you can use `gq` to reflow your selection).

This still ruins the diff view of the code, though. (e.g. git blame)

that's exactly what causes the viewing diff problem that I was replying to

--word-diff=color is your friend in this case.

That's when semantic line-breaking comes into a picture. Put a line break before each new sentence and before each clause in a sentence. That makes the text much more diff-friendly, and tends to keep the line lengths at bay too.

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.

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.

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)

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.

Reply on news.ycombinator.com