5 ms·
Consider reflecting on what you or someone else might mean by "documentation". A submission from 3 hours ago titled "Please don't write your documentation in Ma
by svat 7y ago
Consider reflecting on what you or someone else might mean by "documentation". A submission from 3 hours ago titled "Please don't write your documentation in Markdown" was on the front page earlier: https://news.ycombinator.com/item?id=22675165 https://news.ycombinator.com/item?id=22675165 — but according to its author (https://twitter.com/hillelogram/status/1242502542212333576 https://twitter.com/hillelogram/status/1242502542212333576),
> most people are talking a different kind of "documentation". Most people are thinking of "basic instructions + API", I'm thinking "multithousand-word manuals and reference materials". The latter needs a lot of stuff the former doesn't
With this context, I think it absolutely makes sense that if you're writing something structured (like a book), Markdown may not be the best choice to capture that structure. Of course, if you aren't already sure you're going to have enough documentation "content", then the best choice is whatever gets you writing at all in the first place, whether it's Markdown or Google Docs or emails to colleagues or whatever.
- battery_cowboy 7y agoIf the author wants to write a book, then they're still using the wrong tool, they should be using LaTeX. I agree with everyone here, though, that markdown is great for it's simplicity.
- balfirevic 7y agoThat's pretty illustrative, in that it demonstrates how actually thinking about what you are trying to communicate is going to be much more important than what format you've used to write it. That article would be equally poor in html, latex, markdown or reStructuredText.
- battery_cowboy 7y agoHah! It's almost as if the developer "tool wars" are stupid because everything has its place. Every tool is useful to someone; someone wrote it for a purpose. I think an article like this should be called, "markdown is good, but fur large documentation requirements try ASCIIdoc" and approach it from that angle, and then people would have a chance to compare the two, and maybe use a new technology, without the clickbait title.