Hacker News new | past | comments | ask | show | jobs | submit login
Markdown is an excellent choice for documentation (jeffgeerling.com)
201 points by geerlingguy on March 24, 2020 | hide | past | favorite | 68 comments



For context, posted after this: https://news.ycombinator.com/item?id=22677161


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


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


What you have is nigh-on a Frequently Given Answer, were it not that it is a diary entry. (-:

* http://jdebp.uk./FGA/


And https://news.ycombinator.com/item?id=22675165. This is getting complicated!


What a tangled web, haha.


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


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


I 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


Markdown allows links.


Seriously, “Please document you’re code in the first place” is a great post to promote! :)


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


Good 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/. (I'm not affiliated, just a happy user)

[0]: https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684b...


Every time I hear "X provides more functionality than Markdown", consider it a strong reason to choose MD. I think that The Rule of Least Power (https://en.wikipedia.org/wiki/Rule_of_least_power)

> suggests choosing the least powerful [computer] language suitable for a given purpose

is a good guideline. For every "I need feature X" there should be a question if using this feature is actually beneficial. For general typesetting, we can use general XML, with custom tags. Or anything.

To be clear - I don't mean that MD is the solution for documentation. For many things, we clearly need a different tool. For example, for mathematical papers (with many formulae and cross-references) while we can hack MD to do the job, most likely it won't be the right tool.

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

Most of these things, IMHO, are standard solutions, but not as good when you ask why? E.g. instead of footnotes, inline links (it is not printed on paper, is it?), hand-written table are rarely readable as usually other formats are better, you can easily generate TOC from MD headers structure, etc.


I think this comment illustrates why there's always a debate between markdown vs asciidoc vs xyz.

Markdown is "good enough" for a large amount of people who care less about what seasoned technical writers care about.

> I just reference other functions by name.

(granted a "function name" isn't the best example): when your documentation becomes large enough, your function name will appear in so many places throughout the documentation that you'll want to change it once in one place, and it to appear everywhere else. Having a dynamic variable inside your documentation to take care of this is immensely useful.

This is the kind of feature that other documentation markups offer that (1) you do not need to use but, (2) have at your disposition when you need to.

Now, just to illustrate this with a better example: I wrote user documentation about "how to create a concourse-ci cluster in Google Cloud". This documentation contains a lot of things specific to my organization ("acme"), for example, the VPC network name that needs to be used is fairly variable and depends on the GCE project name but also the region of the project and other things. Depending on who reads the documentation and their project, a few things need to be changed. For this purpose, the top of my documentation contains a few variables that are then used throughout the document in place of hardcoded values.

The variables:

   :concourse-ci-host: ci.acme.io
   :concourse-ci-url: https://{concourse-ci-host}
   :gke-cluster-name: concourse-ci
   :gke-cluster-region: us-central1
   :service-account-concourse-ci: {gke-cluster-name}
   :service-account-concourse-ci-docker-registry: {gke-cluster-name}-docker-registry
   :gcloud-vpc-network-name: {gke-cluster-name}
   :gcloud-static-ip-name: {gke-cluster-name}
   :gcloud-cloud-router-name: {gcloud-vpc-network-name}
   :gcloud-cloud-nat-gateway-name: {gcloud-vpc-network-name}
An example of a section of the documentation about create the firewall rules:

   # Create the network
   gcloud compute networks create {gcloud-vpc-network-name}

   # Configure the firewall to allow all internal traffic and internet traffic to SSH, RDP and ICMP
   gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-internal --network {gcloud-vpc-network-name} --allow tcp,udp,icmp --source-ranges 10.128.0.0/9
   gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-ssh --network {gcloud-vpc-network-name} --allow tcp:22
   gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-rdp --network {gcloud-vpc-network-name} --allow tcp:3389
   gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-icmp --network {gcloud-vpc-network-name} --allow icmp

Which automatically renders:

   # Create the network
   gcloud compute networks create concourse-ci

   # Configure the firewall to allow all internal traffic and internet traffic to SSH, RDP and ICMP
   gcloud compute firewall-rules create concourse-ci-allow-internal --network concourse-ci --allow tcp,udp,icmp --source-ranges 10.128.0.0/9
   gcloud compute firewall-rules create concourse-ci-allow-ssh --network concourse-ci --allow tcp:22
   gcloud compute firewall-rules create concourse-ci-allow-rdp --network concourse-ci --allow tcp:3389
   gcloud compute firewall-rules create concourse-ci-allow-icmp --network concourse-ci --allow icmp
> That’s usually enough.

Until it's not (example above). And it only becomes not enough when your documentation increases in terms of size, complexity of the subject being documented and number of technical writers writing it.

> My coworkers and my future self are adults and can use ‘find’

But your users don't want to use find. They're already too busy learning and understanding your product and the documentation shouldn't get in their way.

Markdown is fine for quick short documentation.

Asciidoc is needed for extensive large documentation.


> Markdown is "good enough" for a large amount of people who care less about what seasoned technical writers care about.

Ahh, I suspect here is the fundamental disconnect.

I suspect few people reading this are technical writers and don't need the tools which a technical writer would use. When they talk about documentation, my expectation is this is code documentation written by developers to be consumed by other developers, not technical manuals or user documentation.


If AsciiDoc hits the sweet spot for your project, great.

For some really serious technical writing, you may need LaTeX. :)

My point is not to dissuade anyone from using AsciiDoc. My point is that I suggest using the simplest tool for solving a gvien problem (documentation writing or a particular project, not for any project).


Makes sense. I looked at LaTeX, but indeed it was a little bit too much! Asciidoc does hit the sweet spot for my particular needs.


Personally asciidoc has too many features, and the asciidoc syntax is baroque.

Cheat sheet: https://powerman.name/doc/asciidoc and there are a bunch of complicated examples on this page: 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
    !==============================================
    |==============================================


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

[1] https://asciidoctor.org/docs/asciidoc-vs-markdown/#compariso...


If you want simple tables just use csv

  |===
  include::customers.csv[]
  |===


Documentation for a software project should be fairly succinct and should be editable by anyone on the project. Developers are exposed to markdown on a near daily basis for other tools like GitHub, StackOverflow, and many other tools.

Markdown is the tool every one of us already know how to use.

> The markdown ecosystem is now riddled with non standard extensions and reminds me the browser ecosystem of y2k

Yet 99% of documentation I've written uses the basic syntax described here: https://daringfireball.net/projects/markdown/syntax

Extensions add to that basic set of tools, so even if you are using Github's flavor of markdown, every single developer on your tool is going to be able to read and edit most of your documentation without referring to any reference material.


I especially like the fact that you can have counters in asciidoc, so you can do interesting kinds of numbering. Trying to do the same in markdown is tricky and it's what actually led me to asciidoc.


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


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


It sounds like you were writing your documents in troff/groff.


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


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


I have. If the "content authoring platform" is not integral to where the source code / original content is written - many people, or I should say most people, tend to just not write it. And then it only gets written with very strict disciplined pre-commit reviews.


Sounds to me like an example where project implementers are unwilling to write it, not that the platform prevented them from doing so.


> I've never seen a documentation effort fail for the choice of content authoring platform.

I also have, multiple times in a 24-year career.

The XML-based monstrosities sold as “enterprise content management” have been bought by many a non-technical manager but never produced useful output once.


I've seen documentation efforts fail because of Confluence's terrible search.


Well, to quote Jordan Sissel (author of Logstash) "Wiki means: where documentation goes to die".

I found maintaining a good documentation inside a wiki tough. People (including me) will tend to create new pages willy nilly, never deleting old ones. The layout is generally rough, you generally have a basic structure, but under that, you see a mess of pages at every levels. The information is often out of date and often redudant which creates noise even if you have quality pages (and even if you have a good search).

The plus side of a wiki is its accessibility. Committing a text file inside a git repository is a tough ask to none technical people. Asking them to "fork" and do a pull request is even harder.

But to maintain quality documentation inside a wiki, a dedicated curator is almost always needed.

It's also not in or near the logical path of code/product changes. You need to login into a dedicated system, find the page you need to change or where to add a new page and finally do the edit. It's kind of hard to have a systematic good documentation in such circumstances. Also, doing reviews and documentation versioning (in sync with product versions) is kind of hard with a wiki.

For all these reasons, I tend to prefer putting my documentation right next to my code in a markup language (simple Markdown README.md for simple projects, RST+read the doc for more complex ones, but that's a personal preference). You have far more incentive to edit the documentation, versioning is automatic, documentation versions are in sync with your product versions, review is easier (just include it inside the PR, same as code review).

The downside is less outside accessibility. It's also a very "low altitude" documentation, great for documenting individual libraries or components, it's not so great for things like documenting overall system architecture, or organizational stuff like processes, basically anything not tied to one specific component.

In the end, wikis have their role, but I found they are generally overused and miss-managed.


I've also had enough with various wikis. And at some point we didn't find a decent tool for documenting our projects. We decided to build our own tool https://nots.io (yay NIH syndrome). The main idea is to make possible to link any type of doc like plain or markdown text, files, google docs right with the code. To give all docs a clear scope. And make it easy to discover what code is documented from the site or IDE. We also track the relevance of each added document. When new commits come in and the code behind the doc changes, we decrease its relevance factor (we call it the fresh rate), and let you know if the document is obsolete now.

We have a demo (https://nots.io/demo). Check it out, I'd love to get feedback.


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


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


Full text search on fairly arbitrary content that will perform well and return high quality results is a pretty hard problem. It is largely a solved problem now, but it takes more work than just throwing everything into a Lucene index.

That said, it is clear Atlassian just sucks at search and doesn't really seem to care. Search in JIRA is even worse if you can imagine that. BitBucket is ok, but a different sort of use case.

I think they could make their search great if they wanted to, but why bother when the people purchasing the product probably won't even use the product enough to notice?


Search is easy - just export whole space and you get big but quite reasonable HTML file which then can be searched with ^F.


Heh. I have done this...


Markdown has no standard table syntax, unless you drop into HTML - for reference: 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)


Personally 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)


Me 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 :)


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


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


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


It'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:

"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/


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


Markdown 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!


LaTeX and Markdown work so well together I wouldn't care to separate the two technologies.


You mean, Markdown with embedded LaTeX?

Show me a widely-available tool for rendering that please.


Pandoc does the job for me: https://pandoc.org/


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


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


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


Amount 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/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=8073620

https://softwareengineering.stackexchange.com/questions/2857...


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


This scenario is not realistic though


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


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


My friend has been working on an open source wysiwyg for markdown which is worth checking out: https://opencodex.dev/demo


I used to just make text files, now I use markdown. Blame GitHub ;)


Markdown doesn't have tables tho. No cross-refs, either.


I haven't found a markdown implementation that doesn't support basic table formatting: 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.


1. Tables are not in the spec.

2. StackExchange Markdown is a prominent example of no-tables.


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


The thing is, in documentation, tables occasionally come up. And even a table of contents is a table...


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


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




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: