
Markdown is an excellent choice for documentation - geerlingguy
https://www.jeffgeerling.com/blog/2020/markdown-excellent-choice-documentation
======
cl42
For context, posted after this:
[https://news.ycombinator.com/item?id=22677161](https://news.ycombinator.com/item?id=22677161)

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

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

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

~~~
j88439h84
> 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
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

------
gouggoug
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/](https://antora.org/).
(I'm not affiliated, just a happy user)

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

~~~
robocat
Personally 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
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...](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/)

[1] [https://asciidoctor.org/docs/asciidoc-vs-
markdown/#compariso...](https://asciidoctor.org/docs/asciidoc-vs-
markdown/#comparison-by-example)

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

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

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

~~~
ksaj
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...](http://www.sngx2.com.br/Help/Epson%20ESC-P2%20Printer%20Command%20Codes.htm)

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.

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

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

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

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

~~~
time0ut
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?

------
zdw
Markdown 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)

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

~~~
spinningslate
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 :)

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

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

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

------
kbutler
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](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
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.

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

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

~~~
einpoklum
You mean, Markdown with embedded LaTeX?

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

~~~
cosarara
Pandoc does the job for me: [https://pandoc.org/](https://pandoc.org/)

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

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

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

------
e2e4
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...](https://mobile.twitter.com/unclebobmartin/status/870311898545258497?lang=en)

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/2857...](https://softwareengineering.stackexchange.com/questions/285787/clean-
code-comments-vs-class-documentation)

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

~~~
gouggoug
This scenario is not realistic though

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

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

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

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

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

~~~
geerlingguy
I haven't found a markdown implementation that doesn't support basic table
formatting: [https://github.com/adam-p/markdown-here/wiki/Markdown-
Cheats...](https://github.com/adam-p/markdown-here/wiki/Markdown-
Cheatsheet#tables)

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
1\. Tables are not in the spec.

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

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

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

