7 ms·
Markdown is an excellent choice for documentation
- m4r35n357 7y agoI used to just make text files, now I use markdown. Blame GitHub ;)
- lukaszkups 7y agoPersonally I use markdown where I can (e.g. my website articles etc.) But I can imagine that for some math-heavy specs the LateX would be a better choice (but I would go with embedding Latex parts into Markdown documents scenario)
- spinningslate 7y agoMe too. I've found markdown + LateX for equations a nice way to write, with minimum friction. Currently trying to sell my daughter on it for her physics project. She's sufficiently frustrated with word's equation editor and randomised picture layout that I might just win :)
- kylepdm 7y agoYeah I don't fully get this whole anti-Markdown sentiment. Have I ever ran into limitations with Markdown? Yes. Has Markdown ever been the reason why things were poorly documented? No. Whatever gets people to document stuff, and maintain and update that documentation.
- cl42 7y agoSeriously, “Please document you’re code in the first place” is a great post to promote! :)
- xtracto 7y ago*Your But yeah, that would be useful. These posts read like fluff to me... I was tempted to write a tongue in cheek post titled "Why it is a bad idea to use a butter knife to unscrew a slot screw". Markdown is a tool, it has some advantages and disadvantages, some people will misuse it, but if you can make it work for you, then that's great. It is just a tool.
- j88439h84 7y ago> Has Markdown ever been the reason why things were poorly documented? Yes. Anytime you see technical docs without structure or links to the functions and classes being discussed, it's because of Markdown.
- t-writescode 7y agoI just reference other functions by name. That’s usually enough. My coworkers and my future self are adults and can use ‘find’. edit: I do use more qualified names, though: className.methodName or filename.extension:function_name
- lonelappde 7y agoMarkdown allows links.
- cl42 7y agoFor context, posted after this: https://news.ycombinator.com/item?id=22677161 https://news.ycombinator.com/item?id=22677161
- dang 7y agoAnd https://news.ycombinator.com/item?id=22675165 https://news.ycombinator.com/item?id=22675165. This is getting complicated!
- geerlingguy 7y agoWhat a tangled web, haha.
- geerlingguy 7y agoI posted this article on my blog mostly because it seems that an anti-Markdown post pops up on HN every 6-9 months, and instead of writing out a comment saying why "just because it is not formally specified doesn't mean it's a bad choice" every time, I can now refer to the blog post :P Seriously, checking my post history I've noticed there have been similar posts saying don't use Markdown but use [asciidoc|latex|rst|etc] over and over through the years. Meanwhile since teams use their own favorite text format, many organizations end up maintaining separate docs for end users in Google Docs, a Word document, or some other system because the non-engineers on the team don't want to spend time learning the ins-and-outs of the special documentation format.
- JdeBP 7y agoWhat you have is nigh-on a Frequently Given Answer, were it not that it is a diary entry. (-: * http://jdebp.uk./FGA/ http://jdebp.uk./FGA/
- sdegutis 7y agoThey pop up this often because it's an unpopular opinion, so it's a fun pastime to read explanations for these things. But that also implies that it's not a serious threat to the common belief, otherwise it wouldn't need to pop up so often. That's my theory anyway.
- metreo 7y agoLaTeX and Markdown work so well together I wouldn't care to separate the two technologies.
- hughes 7y agoI've never seen a documentation effort fail for the choice of content authoring platform. Efforts fail because: - project leaders do not prioritize it - project implementers are unwilling to write it - documentation authors are unable to clearly communicate the important information If the choice of markup becomes the limiting factor, existing documentation can always be transformed (either by machine or manual effort). But missing documentation always seems to come down to one of these three items.
- dharmab 7y agoI've seen documentation efforts fail because of Confluence's terrible search.
- time0ut 7y agoI've given up trying to use Confluence. Our internal instance is a wasteland of smoldering ruins. It is such a hideously bad tool on so many levels, including a "search" feature that will fail you even if you search by exact title.
- folmar 7y agoSearch is easy - just export whole space and you get big but quite reasonable HTML file which then can be searched with ^F.
- time0ut 7y agoHeh. I have done this...
- Tomte 7y agoJust to +1 that, it's my experience, as well. Exact search for the page title does not find the page. How can that be? I mean, isn't that the simplest possible search? And as far as I understand it, Confluence search is powered by Lucene, a world-class library for natural text search. How could Atlassian make it perform that bad? Is there any explanation beyond "they are idiots", because they are probably not.
- CraftThatBlock 7y agoMDX is also pretty nice for more advance formatting, it's Markdown + React. Sometimes, you want to write Markdown but still need to escape to React for custom behaviours, and this does it wonderfully.
- deleted 7y ago[deleted]
- dmlittle 7y agoDo you have any examples where MDX is better than regular Markdown? I don't think I like the idea of needing a JS engine + browser to read documentation.
- ogre_codes 7y agoThe big advantage of Markdown is you can teach it to anyone in about an hour. I built a medical reference web site with hundreds of pages and was able to support a group of about 15 non-techy folks using Markdown plus a few proprietary extensions. I couldn't imagine trying to support them writing HTML or LaTeX.
- fareesh 7y agoIt's also situationally useful for L18N when you are dealing with large article type pages. You can dump out all of the markdown formatted data from your CMS and send it to a translation service - it's much cleaner for them to translate than HTML since they can keep treat the markdown symbols as punctuation for the most part.
- gouggoug 7y agoGood documentation isn't only about it being readable in plain-text. It is about being accurate, maintainable, easy to read (when processed) and even, dynamic (look at Stripe's documentation that contains your own API keys, not random ones). Anybody writing documentation with this goal in mind will quickly realize that Markdown is not fit for the job. Asciidoc is fully compatible with markdown, and provides a lot more functionality out of the box. Basic functionality often needed when writing documentation aren't part of the original markdown spec and require non-standard extensions: tables, footnote, table-of-content, cross references are good examples of this. The markdown ecosystem is now riddled with non standard extensions and reminds me the browser ecosystem of y2k. A quick search on Google allowed me to find this page[0] which lists no less than 20 different markdown flavors. Asciidoc comes in 1 and only 1 flavor that does most of everything you want. Also, there's a great open-source project that allows you to create a documentation website in Aciidoc: https://antora.org/ https://antora.org/. (I'm not affiliated, just a happy user) [0]: https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684baa0f https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684b...
- robocat 7y agoPersonally asciidoc has too many features, and the asciidoc syntax is baroque. Cheat sheet: https://powerman.name/doc/asciidoc https://powerman.name/doc/asciidoc and there are a bunch of complicated examples on this page: https://www.methods.co.nz/asciidoc/newtables.html https://www.methods.co.nz/asciidoc/newtables.html Examples of asciidoc text styling: 'Emphasized text', * Strong text* , +Monospaced text+, ``Quoted text''. 'Subscripts and superscripts': e^{amp}#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^ and ~some sub text~ Example of a nested table (WTF!): [width="75%",cols="1,2a"] |============================================== |Normal cell |Cell with nested table [cols="2,1"] !============================================== !Nested table cell 1 !Nested table cell 2 !============================================== |==============================================
- gouggoug 7y agoYou do not need to use _all_ the features provided by Asciidoc. Here's what I think is a better link[0] than the one you provided. It's the Asciidoc getting started documentation. It's not complicated at all, it looks extremely similar to markdown. If you want to compare MD and Asciidoc side by side, go here[1]. Which one looks more complicated? Now, regarding the table syntax, yes, I agree, it is complicated and that's because tables are complicated. In markdown you don't even have tables, so it's not really fair to say "look at the table syntax in asciidoc WTF, what a mess!". [0] https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ https://asciidoctor.org/docs/asciidoc-syntax-quick-reference... [1] https://asciidoctor.org/docs/asciidoc-vs-markdown/#comparison-by-example https://asciidoctor.org/docs/asciidoc-vs-markdown/#compariso...
- neetfreek 7y agoMarkdown is great! You get just enough formatting with little effort to structure docs well and include URLs and so on as needed. It can be written in any editor. It gets bonus points for being easy to convert to other formats - impress your family and friends today!
- jonperl 7y agoMy friend has been working on an open source wysiwyg for markdown which is worth checking out: https://opencodex.dev/demo https://opencodex.dev/demo
- mfer 7y agoMarkdown is an ok choice for documentation. Poor documentation of a project is not due markdown being used. Good documentation requires different types of docs targeting the different types of docs and different types of users. When it comes to the ability to capture things in docs there's more that's useful than markdown can represent. For example, notes, warnings, etc. Tools like hugo have come up with work arounds that are outside of markdown. Just saying... some things like asciidoc allow capture of richer information. Still, the format isn't going to make the docs good or bad.
- irrational 7y agoThe biggest benefit to markdown is even if every parser was deleted and nobody every wrote a new parser, all markdown documents would still be readable. I do not want a markdown replacement that has functions and includes. That is a terrible idea.
- gouggoug 7y agoThis scenario is not realistic though
- irrational 7y agoWhat? All the parsers going away? Of course not. But it means that I never have to worry about installing an application to read my documentation/notes. As long as I have something that can display plain text, I can read my documents on any device, on any OS, on any terminal, printed out, etc. and they will just work.
- einpoklum 7y agoMarkdown doesn't have tables tho. No cross-refs, either.
- geerlingguy 7y agoI haven't found a markdown implementation that doesn't support basic table formatting: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#tables https://github.com/adam-p/markdown-here/wiki/Markdown-Cheats... It doesn't do native nested tables, or that sort of thing, but for that I'd either drop to HTML or use Pandoc to embed something else inside Markdown. Tables are not fun to format in _any_ plain text language.
- einpoklum 7y ago1. Tables are not in the spec. 2. StackExchange Markdown is a prominent example of no-tables.
- Tagbert 7y agoUse Markdown until it no longer meets your needs, then switch to something more complex. Markdown will likely handle 90% of most people’s needs. Any system that asks you to edit tables in a text editor is asking for trouble. That is a good time to look at a structured editor.
- einpoklum 7y agoThe thing is, in documentation, tables occasionally come up. And even a table of contents is a table...
- justicezyx 7y agoI think the single most important factor of successful technical documentation is to locate documents close to code. Markdown is an excellent choice that strikes a nice sweet spot between expressiveness and being code-like (so can be checked in to repo and live together with the code). Google had done that, and in an exceptional whirlwind by self-motivated engineers who are delighted by having markdown docs in their repo, replaced majority of existing and legacy documentations with markdown files. This thing is called g3doc, and should be well known to people have connections with Google engineers.
- TheRealPomax 7y agoThe only two things markdown is absolutely terrible at right now is maths (because it's not LaTeX) and writing things like vertical Japanese with furigana (certainly, throwing HTML at that problem works for both cases, but it makes things also incredibly untidy for your documentarians). For everything else, there is basically no reason not to use it if you want to write documentation for people to read, rather than produce a typeset product for people to consume.
- zdw 7y agoMarkdown has no standard table syntax, unless you drop into HTML - for reference: https://talk.commonmark.org/t/tables-in-pure-markdown/81 https://talk.commonmark.org/t/tables-in-pure-markdown/81 Nearly every parser implements one of the various flavors, which sometimes don't always work correctly. Markdown is fine for first drafts, then to be pulled into ReStructureText or some other text-oriented but slightly more structured format. I'll give a shout out to Pandoc for making this easy (and for converting between Markdown flavors)
- transitivebs 7y agoAnd in other news, the sky is blue
- deleted 7y ago[deleted]
- subhro 7y agoI am a big fan of LaTEX and write pretty much anything that would ever need to be printed in LaTEX. A former co-worker requested me to write stuff in markdown instead. When I asked why, he (jokingly) told me, Markdown is for people that don't (want) to understand LaTEX yet like the typesetting. These days, I just use pandoc to translate markdown to PDF if I need to print and get almost LaTEX like typesetting.
- kbutler 7y agoIt's somewhat ironic that the author's "I wrote two books in it" LeanPub flavored Markdown format is now deprecated, in favor of Markua, a "newer, better, not-finished-yet" flavor. From the author's link https://leanpub.com/lfm/read https://leanpub.com/lfm/read: "Both LFM and Markua are dialects of Markdown. Markua is newer and better than LFM, but there are still some advanced features in Markua that aren’t finished yet." That's probably the largest criticism of Markdown - it was too incomplete, resulting in many different flavors, each of which may be incompatible with others. That said - documentation in some consistent format is infinitely better than no documentation. Can always Pandoc https://pandoc.org/ https://pandoc.org/
- eska 7y agoI wasn't under the impression that markdown is criticized so often on here as claimed in the article. However, from my experience of constantly dragging my colleagues to writing some small spec/docs, I would definitely fail if they had to learn anything at all in order to do so.
- ksaj 7y agoI already do all my work in markdown. I got into the habit because of github, and haven't turned back since. The "killer feature" was that my documents work absolutely everywhere, and can easily be converted to a Word, PDF or HTML document on a whim. Leave the format "prettiness" to style sheets where it belongs. The side effect is that it clobbers the multiple-styles problem many corporate documents amass after more than a few people have edited them. The number of documents I've worked with that had UK, Canadian and US English all embedded in a paragraph-by-paragraph manner over the years... Mind you, I started out in that frame of mind, since at the end of the 80's I used to write all my documents in a format that I no longer remember the name of. What I do remember is that it used dot codes, so something italicized would start with .i and .u for underlining. The purpose was to allow the dot matrix printers to over-strike, which provided much higher print resolution than the printer would normally be capable of. It had higher level codes for things like titles, etc, which is the connection I make to markdown. Markdown languages allow you to get things looking reasonably good with extremely few attention-diverting things like format getting in the way of progress.
- Amelorate 7y agoIt sounds like you were writing your documents in troff/groff.
- ksaj 7y agoI do think it was influenced by troff, since they do bear some visual similarities. A little googling didn't find what it was, but I do believe it was directly related to this: http://www.sngx2.com.br/Help/Epson%20ESC-P2%20Printer%20Command%20Codes.htm http://www.sngx2.com.br/Help/Epson%20ESC-P2%20Printer%20Comm... Except that the escape was replaced by a dot for the driver that converted it, and more "user friendly" formats like title (which was centered, bold and underlined). But I'm literally guessing since it was so long ago.
- ethhics 7y agoWorse is Better versus The Right Thing strikes again. I find that I can extend Pandoc’s markdown to do most of anything I’d want. Could RST or AsciiDoc do it better? Maybe. I haven’t tried. But markdown can do 80% of what I need right out of the box.
- jdoliner 7y agoI see a lot of similarity between Markdown and Golang, both have a lot of critics with some reasonable criticism. They're both limited in ways that competing languages aren't, but somehow they both just feel so productive to me. Some combination of the right feature set, stripping everything else away, and focusing on simplicity just works for me.
- e2e4 7y agoAmount of documentation (comments) still seems to be an open question. e.g. Bob Martin (Clean Code) wrote: A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail. https://mobile.twitter.com/unclebobmartin/status/870311898545258497?lang=en https://mobile.twitter.com/unclebobmartin/status/87031189854... I use to be proponent of comments throughout the code. But lately, am leaning more and more towards minimization through proper naming, annotation, function design (e.g. no side effects, single functionality). Here are some related materials: A more complete quote from `Clean Code` Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation. Comments are not like Schindler's List. They are not "pure good." Indeed, comments are, at best, a necessary evil. If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much -- perhaps not at all. The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn't some way to turn the tables and express yourself in code. Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression. Previous related Discussions on NH: https://news.ycombinator.com/item?id=8073230 https://news.ycombinator.com/item?id=8073230 https://news.ycombinator.com/item?id=8073620 https://news.ycombinator.com/item?id=8073620 https://softwareengineering.stackexchange.com/questions/285787/clean-code-comments-vs-class-documentation https://softwareengineering.stackexchange.com/questions/2857...