Hacker News Reader

Comment by dplavery92 | Hacker News Reader

It doesn't appear to me that the article linked in the rebuttal thread appears to address any of the points made in this article. Instead, the author offers that he's written two books and thousands of blog posts in Markdown, and claims (without substantiation) that 98% of all code documentation could be written in Markdown.

Where does that leave us on any of this article's concerns about extensibility and cross-reference? I'm persuaded by the need for a richer set of tags and non-local references for writing code documentation on most of my projects.

View on HN

It depends more on what platform you're targeting. On GitHub, cross-reference is easy enough with links (ala hyperlinks) using relative paths. On LeanPub, I can add notes and references with their small extensions.

For most documentation, though, the basics are good enough. For some projects, yes you may need more structure, and either building a custom docs site or more heavily customized documentation is a good idea.

But even for medium-sized doc sets, Markdown still works great (I maintain a Docs site for Drupal VM[1] using Markdown with Read the Docs).

[1] http://docs.drupalvm.com/en/latest/

but also on github as soon as you change the header your reference needs to be updated

There is lots of plugin support for markdown that the article doesn’t consider. I actually wrote some documentation in markdown that used a plug-in to embed markdown generated flow charts and then exported to PDF to create portable documentation. The article makes decent points but there’s no wrong or right answer it’s situational.

Plugin support for a bad idea doesn't make the bad idea better.

Why not? Lots of crappy products have been improved tremendously by third-party plug-ins.

"Bad executions of an idea" is very different than "a bad idea"

> It doesn't appear to me that the article linked in the rebuttal thread appears to address any of the points made in this article.

The arguments are weak to mind boggling, and the technical nit-picking would better addressed by suggestions on how to support those minor features in markdown.

It makes absolutely no sense to complain about the document format when commenting on documentation.

> It makes absolutely no sense to complain about the document format when commenting on documentation.

Why not? When aren't formats important? Or is it the fact that it's documentation that makes it not worthwhile to comment on?

Reply on news.ycombinator.com