3 ms·
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 th
by dplavery92 7y ago
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.
- geerlingguy 7y agoIt 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/ http://docs.drupalvm.com/en/latest/
- serverQuestion 7y agobut also on github as soon as you change the header your reference needs to be updated
- rumanator 7y ago> 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.
- lallysingh 7y ago> 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?
- alexfromapex 7y agoThere 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.
- naikrovek 7y agoPlugin support for a bad idea doesn't make the bad idea better.
- lowtolerance 7y agoWhy not? Lots of crappy products have been improved tremendously by third-party plug-ins.
- naikrovek 7y ago"Bad executions of an idea" is very different than "a bad idea"