
Don't write documentation in Markdown - randyzwitch
https://buttondown.email/hillelwayne/archive/please-dont-write-your-documentation-in-markdown/
======
dang
Concurrent rebuttal thread:
[https://news.ycombinator.com/item?id=22677970](https://news.ycombinator.com/item?id=22677970)

Follow-up supporting thread with older article:
[https://news.ycombinator.com/item?id=22677161](https://news.ycombinator.com/item?id=22677161)

~~~
dplavery92
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
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/](http://docs.drupalvm.com/en/latest/)

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

------
husarcik
This reminds me of a comment on an anti-markdown post I read a few years back.

 _" As far as I'm concerned the best tool for writing documentation is the one
that anyone can actually be bothered to use. Markdown might not be perfect but
at least it's simple and commonly understood so there isn't much barrier to
writing/updating documentation." \- warmans_

[1]
[https://www.reddit.com/r/programming/comments/4ck2lu/why_you...](https://www.reddit.com/r/programming/comments/4ck2lu/why_you_shouldnt_use_markdown_for_documentation/)

~~~
Aardwolf
My biggest gripe with markdown for writing is its removal of single
intentional newlines.

~~~
antipaul
I think you can achieve that with 2 spaces at the end

~~~
Aardwolf
Yes, but, my gripe is how markdown breaks standard plain text behavior,
without requiring _extra_ formatting (those two spaces). They should have
required the extra formatting for the opposite case, if you want to break a
line in your code for some reason but not in the final result. Confusingly
those two spaces also don't work in hacker news comments while some other
markdown features do.

If it was like plain text, with a few ascii symbols used for formatting (like
*, _, ...), it'd have been more fantastic than now.

BBCode is better imho.

~~~
jachee
> while some other markdown features do.

The _only_ two markdown features afaik that work on HN are italics with
asterisks and code blocks with 4 spaces.

That's it.

------
1MoreThing
This is missing the point.

The goal is "please write your documentation." What solution has the least
friction around that for engineers? Right now, it's overwhelmingly Markdown.

It's not perfect, and often doesn't provide the features a technical writer or
other content specialist might want, but it handles most use cases and is
something developers are willing to write in.

So please, write your documentation in whatever you feel like. As long as it
gets written.

~~~
dllthomas
For me, the biggest source of friction when I sit down to write documentation
is the knowledge that what I write will eventually wind up out of date and
misleading - which can be worse than missing.

What processes or tools do you know of to keep documentation up to date as
code and environment change underneath it?

~~~
afarrell
Here is my proposal for any sort of docs that don't live right alongside the
code. I have yet to put this into practice.

There are 4 states for any page:

\- Maintained: "We are maintain this and aim to keep up to date. Message
#slack-channel with any questions."

\- Stale: "Oops... we didn't."

\- News: "This represents our current thinking as of 23-Mar-2020"

\- Record: "This is a historical record of our intended system design,
produced on 4-Aug-2018."

When you write docs, be very clear whether you are writing a new report or
something you intend to maintain. Reports become historical records after 1-3
months. Default to a report.

Why? To keep small the number of docs which are "Maintained". Every maintained
page is owned by a team of 2-10 people and the channel to contact them is
visible on the page. Ideally, there would be a tool which attaches to every
"Maintained" page and does 3 things.

1) Let the reader mark it as possibly stale or ask a question, then messages
the page owners about that. Marks the page as stale within a week of non-
response.

2) Mark the page as stale if the text isn't updated at least every 3 months.

3) Mark the page as stale if it doesn't get at least N page-views in 3 months.

I'm serious about point #3. If a page is rarely-read by others, then the team
which owns it is not pointing people to it or using it for training. If that
is the case, then why should they spend time and attention to keep it up-to-
date?

Is it an emergency runbook? Well then either that info is important enough to
walk through it periodically, or you should be honest with yourself that what
that doc really says is, "This was the suggested runbook we came up with after
a post-mortem 2 years ago. It might be very useful for understanding the
system. Maybe it even still works."

~~~
dceddia
This would make a great plugin for something like Confluence. Most places I’ve
worked, the wiki was where information went to die. It’d be nice if the
unused/outdated stuff could fade away automatically-ish.

------
taylodl
Meanwhile programmers are like: Please write documentation! Please. I'm
begging you. Even documentation written in Markdown is better than the nothing
that all-too-often gets created.

A lot of programmers argue the code is the best documentation. No it's not.
Source code answers the _how_ and _what_ but it doesn't provide any answer to
the most important question of all - _why?_

Software embodies several architectural and design decisions. What decisions
were explicitly made and why were they made? All too often when looking at
code I can certainly understand _what_ was done, but it's not at all
immediately clear as to _why_.

On the teams I've been working with I've gotten them to capture these
decisions. It's been a great help - sometimes the original implementors can't
remember why something was done the way it was done - especially when asked
three or more years later.

Admonishing people to write documentation in Markdown would be a nice problem
for me to have. Meanwhile I'd just like some documentation at all. Please?!

~~~
ken
> Source code answers the how and what but it doesn't provide any answer to
> the most important question of all - why?

The vast majority of technical documentation I read doesn't answer _why_ ,
either. The closest examples I see these days are tech talks (e.g., videos of
Rich Hickey talks) and FAQs (e.g., the Python FAQ has a number of "why"
questions). Sometimes also source code comments (e.g., the Swift stdlib
actually has fairly informative comments).

For some reason, even though there is clearly demand for the _why_ , and
programmers are happy to supply it, nobody ever wants to provide it inline, in
the documentation proper.

It's a rare, rare piece of software that doesn't at some point make me tear my
hair out and ask "why?!" upon discovering some behavior which is working
exactly as documented.

------
drcongo
I can't stand reStructuredText, it's obtuse. Over the last year or so have
converted all of our documentation to Markdown and I couldn't be happier about
it.

~~~
corndoge
I've had the markdown vs rst discussion with a few people a few times and the
pro-markdown people always cite this, saying rst is much harder to use or the
core syntax is awkward in comparison. I don't really understand this, the same
markup you get from markdown has about the same surface area in terms of
syntax in rst. `code` vs ``code``, or just an indented block (in rst just add
:: before the block start), _emph_ is still _emph_ , you can still use = and -
for headers, bullet lists are the same as markdown, and so on. Inline
hyperlinks are about the only thing that aren't visually nice like they are in
markdown, (text)[link] vs <text `link`>_ or w/e it is (I use sphinx refs so I
don't recall exactly). Actually in a way rst is better for links since the
common thing in markdown is to reference links like this[0], in RST with _
instead that actually works and this becomes a hyperlink. Like the basic
features are mostly identical. But then when you start needing features for
big documents like cross references, highlighted syntax blocks, images, ToC,
figures, etc it RST has all that built in and you don't have to reach for some
markdown superset (although I guess you could argue Sphinx is that for RST). I
dunno, I've done both and I just have a much better time with RST once the
project size gets past a single doc.

I still use md for READMEs and gists and whatnot, I guess my point is,
different tools for different jobs, if you have to pull weeds in your garden
use a spade, if you have to do it for a field use a machine, or something.

~~~
benhurmarcel
> you can still use = and - for headers

You can't make section headers with ##, no?

More importantly in RST you can't easily manage several levels of headings.
You're limited to 2 or 3, and have to remember which underline character you
used for that level.

~~~
WorldMaker
In rST there are three choices of "line-style": underline, overline, both
under and overline. Then there's dozens of possible symbols ("printing
nonalphanumeric 7-bit ASCII character"), and the documentation/primer narrows
that to a suggested interesting looking 14 options of ASCII symbols. That's a
total of 42 suggested options for heading levels, and not even the "limit".
There remains the practical limit that Markdown also inherits that HTML only
has 6 levels.

There's not a suggested or standard order, so yes there's some mental overhead
in deciding which header styles you want to be which level, but a lot of
projects tend to have a "lint" guide for that at this point. For instance a
lot of projects (and Sphinx recommends) follow the Python Style Guide:

    
    
        # with overline, for parts
        * with overline, for chapters
        =, for sections
        -, for subsections
        ^, for subsubsections
        ", for paragraphs
    

(You may be confusing Markdown's/CommonMark's own less popular Setext-style
headers which only support underline and = for first level and - for second
level header.)

------
JMTQp8lwXL
There's hills that seem worth dying on. This doesn't seem to be one of them.
The author says it's "tolerable" to use markdown for a README.md, but in many
small projects -- that's all there is. Besides the code, there's the README.
When I think of larger open source projects, I don't see intricate or
excessive usage of markdown. They have full blown websites-- React, Jest,
Material UI-- you name it. I don't see a single actual example of the problem.

~~~
slowmovintarget
This is another of those sad cases where worse is better. AsciiDoc, and
perhaps RST, are superficially better by measures of specification-
completeness and uniform handling of corner cases.

Markdown is used everywhere, so it "won". Better doc in a "worse" format than
no doc at all.

~~~
lmm
RST is clunky to write. Markdown "won" because it solves the most important
part of the problem - humans feel comfortable writing it.

------
lhorie
This is committing a fallacy I see far too often at my company: that because
something is considered "technically superior" it should be the tool of
choice. This misses the human aspect of a system. Markdown has low barrier of
entry, and in a world where more often than not, documentation is poor or non-
existent, it doesn't really matter if a documentation system has many bells
and whistles if those features get seen as too difficult to learn and result
in no docs being written in the first place.

Another important human aspect of documentation is docs are often written by
people joining a project late who may already be knees deep trying to
understand the projects APIs. Burdening them with learning a documentation
system on top of that can definitely a tipping point between "I should
document this" to "ah whatever, I'll just slog through the code".

~~~
p1necone
AsciiDoc specifically is pretty nice though, I prefer it to markdown and it
doesn't really have much more of a learning curve.

------
walterbell
AsciiDoc is compatible with Markdown and can generate many output formats,
including Docbook and Latex, which enables toolchain reuse. This provides more
optionality than RST.

The most important property of documentation is existence. Markdown has a low
barrier to entry and the markup can later be upgraded to Asciidoc.

~~~
jessaustin
This is not the only comment ITT to recommend Asciidoc. It seems interesting,
so I looked into it. On the asciidoc Github page [0], I found this note:
"NOTE: This implementation is written in Python 2, which EOLs in Jan 2020.
AsciiDoc development is being continued under @asciidoctor."

In other words, upgrading to py3 was such a pain, they rewrote it in Ruby
instead. Ouch! This has got to be the worst example (among more than a few) of
py3 pain I've seen yet!

[0]
[https://github.com/asciidoc/asciidoc](https://github.com/asciidoc/asciidoc)

~~~
fcurts
The Ruby implementation (Asciidoctor) is a separate implementation by a
different team. I recommend to use it together with Antora (Asciidoc's answer
to Sphinx).

~~~
jessaustin
Sure, that seemed likely. The python repo seems pretty unambiguously
deprecated, however.

~~~
Somasis
Except that the version most distributions that are ridding themselves of
python2 are using is a new python3 ported version. As far as I know the
maintainer of that repository isn't touching it anymore, which is why it isn't
linked. [https://asciidoc3.org/](https://asciidoc3.org/)

------
rvz
> Developers: reStructuredText is better than .txt and .md because it has
> feature XYZ, and it's special syntax is great.

> Researchers: .rst and .md are poor with math symbols, please write the
> technical documentation in beautiful LaTeX with rendered symbols.

> Managers: If I can't read or edit it easily, I'll hire someone to rewrite it
> using Word or Google Docs.

> Everyone: Here's the Word document...

> Scribe: 𝔜𝔢 𝔬𝔣𝔣𝔦𝔠𝔦𝔞𝔩 𝔡𝔬𝔠𝔲𝔪𝔢𝔫𝔱𝔞𝔱𝔦𝔬𝔫 𝔰𝔥𝔬𝔲𝔩𝔡 𝔟𝔢 𝔴𝔯𝔦𝔱𝔱𝔢𝔫 𝔟𝔶 𝔥𝔞𝔫𝔡 𝔞𝔫𝔡 𝔰𝔢𝔱 𝔦𝔫 𝔰𝔱𝔬𝔫𝔢
> 𝔴𝔦𝔱𝔥 𝔭𝔢𝔫 𝔞𝔫𝔡 𝔭𝔞𝔭𝔢𝔯.

> Me: Meh. if everyone can't read or edit it quick enough towards the
> deadline, then I'll stick to Google Docs.

------
Athas
While I acknowledge that Markdown's lack of extensibility is a big problem,
one that RST doesn't share, RST has its own problems. For example, this is how
you write a link in RST:

    
    
        `link text <https://news.ycombinator.com>`_
    

Obscure, but OK. This is how you put something in monospace:

    
    
        ``monospace``
    

So then how do you make the link text contain monospace formatting? Last I
checked, there was no clean way. Using non-matching bracketing characters is a
terrible idea because it inhibits nesting, which has been known at least since
POSIX shell introduced $(). There is really no excuse for the way RST uses
backticks. This is a major reason why I prefer Markdown.

~~~
zelphirkalt
It might be possible via custom roles.

~~~
zelphirkalt
Not sure why this is downvoted, as it is a purely informative comment, which
might help the GP to implement something they need.

~~~
zihotki
Probably beause it's not user friendly. It's better when it's simple, it works
well and predictable out of the box.

------
karlicoss
Not sure about proper documentation, but I've found Org-mode to be quite
enjoyable for writing readmes, mainly because of its org-babel [0] (aka
executable code blocks) support. That way you can include/tangle bits of
source code and help strings documentation in the readme, avoiding unnecessary
duplication. The results of the evaluation are committed to the repository as
well, and it's plaintext, so you don't need Emacs to fix/update the docs --
you can patch up the evaluation results, and the maintainer with Emacs can fix
it properly later.

E.g. here [1] I'm reusing the argparse help string in the readme. That makes
the source code the primary source of truth.

Another experiment I did was writing readme as an Ipython notebook [2], and
then compiling the output to markdown. That allowed me to link bits of readme
straight to the code. E.g. as an example, each of the 'Features' [3] links
straight to the unit test for that specific feature. The downside is that you
need to remember to refresh the readme after code changes, otherwise the line
numbers break. Perhaps that can be set up automatically as a CI job.

In hindsight through, would have been easier to use org-mode as well to avoid
keeping two separate files for the readme.

\- [0] [https://orgmode.org/worg/org-
contrib/babel/intro.html](https://orgmode.org/worg/org-
contrib/babel/intro.html)

\- [1]
[https://github.com/karlicoss/rexport/blame/master/README.org...](https://github.com/karlicoss/rexport/blame/master/README.org#L15-L17)

\- [2]
[https://github.com/karlicoss/cachew/blob/master/README.ipynb](https://github.com/karlicoss/cachew/blob/master/README.ipynb)

\- [2]
[https://github.com/karlicoss/cachew#features](https://github.com/karlicoss/cachew#features)

~~~
sbrass
Thanks for your interesting insight in your projects.

I'm using org-mode profoundly since 2015 for a lot of my daily note taking
routines. Additionally, I've started two years ago to work some of my
readmes/tutorials with org-mode. It provides a fantastic way of helping to
write, where I find it much more graceful than RST (or Markdown at all).

One of the reason of change to org-mode, however, was its excellent code
blocks and noweb-like feature - as you told residing in org-babel. However,
that is not what org-mode was buying for me, but the sheer extensibility and
that you can use it now everywhere (e.g. for static page builder like Jekyll
or wiki-pages based on Gollum).

I recommend everyone to peek at the excellent Spacemacs project,
[https://www.spacemacs.org](https://www.spacemacs.org), for an org-mode
experience out-of-the-box.

------
zelphirkalt
I'd also recommend people to make use of reStructuredText for documentation.
Also it is actually possible to write something like a thesis or scientific
research in it, where you might need arbitrary linking powers, which you
simply don't have in Markdown. This can also be important for technical
documentation. Furthermore you can add custom roles, like I did for my
personal wiki implementation, to link to other pages, which are actually other
reStructuredText files.

The downside of reStructuredText is, that there are almost no libraries in
other languages than Python, which can transform it into HTML for the web. The
canonical parser is a custom parser, without grammar and lots of states, which
is unfortunate, because if there was a grammar, it could easily be implemented
in other languages and the format might be much more used. But perhaps it
would not be as extensible then?

Another, but quite minor, downside is, that it is a little bit harder to learn
than Markdown.

Perhaps I can suggest Emacs Org-mode? The downside is, that it's only
available to the extend in Emacs and other implementations are lacking many
things.

Anyway, I wrote a thesis in reStructuredText and used Pandoc + custom
preprocessing for document internal linking to generate the final PDF version
and once I had it set up, it worked great.

------
oefrha
AsciiDoc is pretty good, yes. But reST? Just no.

As a Python developer I’m no stranger to reST, and problems like the inability
to nest inline constructs (e.g.
[`code`]([https://example.com](https://example.com)) is impossible in reST)
are simply ridiculous. (Talking about docutils here. Maybe there are other
unofficial implementations that fix some of the problems, but anything not
used by Sphinx is rather useless.)

I used to have READMEs of Python projects in reST because of PyPI
long_description; those were converted to Markdown soon after PyPI started
supporting Markdown. Now I write reST exclusively for Sphinx (mostly in the
form of autodoc), but need to check documentation all the time.

~~~
type0
About reST. It's not just difficult to write, most of the time it's also
jarring to read. Org-mode isn't very rosy to write either but at least I can
scan the document and understand how it will render.

For the language that focuses on readability Python has completely missed the
boat here.

------
dfee
I have documented a moderately complex package in RST [0]/[1] and another in
MDX (and a mix of MD & JS) [2]/[3] and have tons of $company docs written in
MD.

My thought is that RST is probably closer on the spectrum to LaTeX (despite
still being far away) as it’s a more powerful syntax with a more esoteric
format.

If you’re a sole contributor or want to limit your contributors to those who
know or have the patience to learn this, then sure, use RST.

Otherwise, documentation is a team sport. Write in whichever format will let
people get ideas down fastest and can most easily be coerced it formatted
text. Right now, the best option for that is MD.

These aren’t algorithms, so trade power for participation.

[0]
[https://github.com/dfee/forge/tree/master/docs](https://github.com/dfee/forge/tree/master/docs)

[1] [http://python-forge.rtfd.io/](http://python-forge.rtfd.io/)

[2] [https://github.com/dfee/forge](https://github.com/dfee/forge)

[3] [https://dfee.github.io/rbx](https://dfee.github.io/rbx)

------
GordonS
I've been writing all my documentation in AsciiDoc for the past few years, and
I love it! As another commenter mentioned, it's even compatible with markdown.

I previously used Microsoft Word for all documentation, but the lack of human-
readable diffs in source control was a PITA, and some features are just much
better in IDEs that Word (e.g. search and replace with regex).

------
kick
This person's criticism is silly. Markdown documents _are_ extensible: the
entire point is that it makes the main parts require less cognitive load, and
allows you to use HTML for the rest.

    
    
        ## CHAPTER IV.
        #The <white>Rabbit</white> Sends in a Little Bill
    
        It was the <white>White Rabbit</white>, trotting slowly back again, and looking anxiously about as it went, as if it had lost something; and she heard it muttering to itself *“<red>The Duchess</red>! <red>The Duchess</red>! Oh my dear paws! Oh my fur and whiskers! She’ll get me executed, as sure as ferrets are ferrets! Where can I have dropped them, I wonder?”* <gold>Alice</gold> guessed in a moment that it was looking for the fan and the pair of white kid gloves, and she very good-naturedly began hunting about for them, but they were nowhere to be seen—everything seemed to have changed since her swim in the pool, and the great hall, with the glass table and the little door, had vanished completely.
    

Just write the two lines of CSS required for those elements, and bam! You're
all good!

They criticize this within, but their criticism isn't particularly strong:
sure, the point of Markdown is to write less HTML, but in this instance, the
HTML is about as semantically concise as you can get: the quickest solution in
any system. Their comment on hybrid documents also doesn't really work in the
context of most parsers.

~~~
type0
It was the <div class="white">White Rabbit</div>

It emerged at the time when HTML was the lingua franca of the Web. Nowadays
with so many new ways to create web pages you can't count on it, so
contributors who aren't familiar with it will spend unnecessary time on fixing
HTML and CSS instead of fixing the docs.

~~~
kick
A div isn't the right thing to use here. Am I missing the point of your
example? It seems like it could be a way to demonstrate how people don't know
HTML, but I'm not sure.

------
arthurofbabylon
There’s sentiment here on HN that any documentation is good documentation -
and while it is better than NO documentation, it’s just not correct to dismiss
truly great documentation.

For example, Stripe (the workplace of the author) has incredible documentation
that single-handedly enabled me to build with it, despite my being a wretched
server-side developer.

That the documentation alone doubled the potential user-base, thus fostering
growth and engagement with the product, is a testament to the power of great
document versus just documentation.

V1 docs in markdown - fine. But V2 for an ambitious tool should probably start
approaching what Stripe is accomplishing.

~~~
hwayne
Small correction: I don't work at Stripe! The person who made Buttondown does,
I just use it for my newsletter.

~~~
arthurofbabylon
Ahh ahh, my bad, and thank you for the correction.

------
virtualritz
I've been using ReST w. Sphinx since years and it's not the answer either.

Consider this simple fail of nested styling:

    
    
      *I am italic but also **bold**.*.
    

This produces (all in italics but lacking any bold text):

    
    
      I am italic but also **bold*.*
    

If you assumed asterisks could be stacked; nope:

    
    
      *I am italic but also *bold*.*.
    

Produces (all in italics but lacking any bold text):

    
    
      I am italic but also *bold.*
    

ReST/Sphinx can't do this. Doh! Because of this you can also not have styling
in e.g. link texts etc.

These limitations seem unnecessary and random. For example, when the parser
handles a table, which is also just marker symbols for cells, you can have
styled text or links in the cell's text. Why this works but nesting styles
doesn't is completely beyond me.

------
goodSyntax
Rust documentation uses markdown and it is amazing. Not sure what this person
is on about. Everyone also knows Markdown very well. Also, if you are trying
to color certain parts of your documentation blue, I think you're focusing on
the wrong things.... Documentation should be about example code, which is
perfectly fine in Markdown, you simply go:

```code <example> ```

Also I don't agree with the author's points about links in Markdown
whatsoever.

~~~
kenhwang
Rust documentation is amazing because of the toolchain support for
documentation tests. Markdown is just... there.

------
h3rald
I beg to (partially) disagree... (shameless plug ahead!)

[https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm](https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm)

OK, you are right that _ordinary_ markdown is insufficient because a lot of
functionalities are missing for proper technical writing and above all proper
content reuse...

That's why in my tool I started from an already fairly-advanced Markdown
flavor (Discount) which already comes with a bunch of proprietary extension...
then on top of that I added things like snippets, transclusions, fields, and
even simple macros.

------
thangalin
My blog dives into Markdown, Pandoc, R, bash, and the ConTeXt typesetting
engine.

[https://dave.autonoma.ca/blog/](https://dave.autonoma.ca/blog/)

Part 8 (coming soon!) uses annotated Markdown to reproduce a famous poem
(original is on the left):

[https://i.imgur.com/idV1mTM.png](https://i.imgur.com/idV1mTM.png)

The text of the poem is written in Pandoc-flavoured Markdown:

    
    
        ::: poem
        Some say the world will end in fire,
        Some say in ice.
        From what I’ve tasted of desire
        I hold with those who favor fire.
        But if it had to perish twice,
        I think I know enough of hate
        To say that for destruction ice
        Is also great,
        And would suffice.
        :::
    

> Markdown is good for generating HTML and terrible for making PDFs.²

Yes, Pandoc is essential for transforming Markdown into beautiful PDF files.
Tooting my own horn a little more, my illustrated photobook, Impacts, is
written almost entirely in pure Markdown, with a few annotations for plots and
spectra:

[https://impacts.to/preview.html](https://impacts.to/preview.html)

Tangentially related, what would be amazing is a robust text editor that
allows injection of interpolated string variables from various data sources
and structured data formats. Here's an architecture diagram to clarify:

[https://i.imgur.com/8IMpAkN.png](https://i.imgur.com/8IMpAkN.png)

My open-source editor, Scrivenvar
([https://github.com/DaveJarvis/scrivenvar](https://github.com/DaveJarvis/scrivenvar)),
implements that architecture to some extent.

------
soulnothing
I'm a big proponent of contract and document based development. Easing on
boarding, and correlating the current architecture with active documentation.
I usually keep software centric, in git along side the code.

Coming from Python I was a big fan of sphinx. With Graphviz we were able to
embed flow charts of micro services. It worked very well. There are a number
of extensions made it very powerful.

I switched because it felt close to markdown but not markdown. I now use
docsify[0].js. There are a few things I miss. But it's an easier transition as
my docstrings are also markdown. So no context switching.

Markdown is very bare. But that I feel keeps the documentation simple. With
less knobs to twist, the documentation has less accents to it. With that
limited range I feel it's more important to have a style guide.

[0] [https://docsify.js.org/#/](https://docsify.js.org/#/)

------
paultopia
This seems quite silly. As many other people have said in these comments, RST
is an obscure mess. By contrast, Markdown is supported by every editor, every
static site generator, countless other applications, and is trivial to learn
and to use.

Also silly is to complain about stuff that everyone uses, like tables, not
being part of the markdown spec. We have amazing tooling around markdown, like
pandoc, who cares whether it's part of the spec?

------
nnq
...Org mode anyone? [https://orgmode.org/](https://orgmode.org/)

------
chubot
The best part of Markdown is that you can embed HTML, and the author gets it
wrong by saying you can't mix the two freely.

In CommonMark (and thus most modern Markdown implementations) you can embed
Markdown in HTML like this:

    
    
        <table><tr><td>
    
        *This is markdown*
       
        </td></tr></table>
    

You need blank lines before and after the tags.

I think you could do this in markdown.pl but there were some
quirks/limitations.

\----

Related: _CommonMark is a Useful, High-Quality Project_

[http://www.oilshell.org/blog/2018/02/14.html](http://www.oilshell.org/blog/2018/02/14.html)

------
csours
Invoking Cunningham's Law:

Appeal to Mundanity: I've supported dozens of systems over the last 15 years,
here are my opinions:

The best documentation is the implementation.

The second best documentation is any documentation at all.

The better you reveal your implementation, the better your documentation.

If you want to improve your second best documentation, knock yourself out.
Concentrate on documenting interfaces and the location of your primary
documentation (the source code, settings, etc)

If you want to bikeshed your second best documentation, I'm afraid I'm just
going to laugh at you.

------
luckyorlame
Please don't write "Please don't write your documentation in Markdown"

------
bjoli
XML solves these problems a long time ago. It has been abused so much that
people don't consider it anymore, but I have been using 2 personal DTDs since
about 2005 and I have been laughing every time people have complained about
whatever shortcomings their markup language of choice has.

you can use any programming language to work with it, and using scheme and
SSAX makes even XSLT a breeze.

------
ChuckMcM
So many re-inventing SCRIBE from the '80s. Kind of funny actually.

In the 70's and 80's we used ASCII terminals to edit documentation, and only
some terminals supported attributes like bold, italic, and underline. But you
needed to be able to read it in its "raw" form.

So there were many systems developed that let you put the "markup" inside the
document and keep it as reasonable as possible. The one I wrote a number of
term papers in was SCRIBE that ran on the TENEX later TOPS20 machine and put
the "final" output to a Diablo Hytype printer.

Consider that you had a team of 20 software developers working to build a
software package for writing text documents that could both be read when being
created/edited and later processed into beautifully typeset documents using a
film typesetter.

This in contrast to a developer saying "hmm I'm putting up all this stuff in
HTML and typing too much, I'll add a few shortcuts here, here, and here. Ta
da! It works for me."

The availability of cheap dot matrix displays and "desktop publishing" set
aside all those goals of editing with a text editor and instead using
"WYSIWYG" environments of increasing complexity and bloat.

I applaud the reStructuredText people for wanting to attack the problem but I
really wish they could look at what has already been done in this space to
avoid the mistakes of the past. A version of SCRIBE that was UTF-8 clean would
be pretty awesome as a starting point.

In my own workflow I find working in text faster because if I use a WYSIWYG
editor I get so distracted by it looking "wrong" that I can't focus on the
text itself. I would truly love something that was TMWYW (tell me what you
want) rather than something that keeps trying to show me what it thinks I
want.

~~~
samsquire
I am trying to write a layout engine that is TMWYW.

[https://github.com/samsquire/additive-
guis](https://github.com/samsquire/additive-guis)

~~~
ChuckMcM
That is pretty cool!

------
gravypod
Many people I've worked with in the past have unfortunately shared the
sentiment of the author. I think the issue is sustainability of documentation
practices. There's a desire path that engineers exhibit when writing docs. We
just want to write something and have others be able to read it. Markdown is
the lowest barrier of entry because, even without any special characters, my
plain text will look "fine" in Markdown. Nothing is truely required.

To me the two most important things are:

1\. Docs are tracked with software updates (track in VCS)

2\. Enable me to spend less time writing docs and more time writing code

Google documented their experiments with markdown documentation here:
[https://www.usenix.org/sites/default/files/conference/protec...](https://www.usenix.org/sites/default/files/conference/protected-
files/srecon16europe_slides_macnamara.pdf)

------
oweiler
With Pandoc you can easily generate LaTeX from Markdown and then turn that
into a PDF. This gives you best of both worlds.

~~~
dalai
How does that work if you want a table or a figure or an equation? Is it still
markdown and still as easy to read and edit by everyone if there are LaTeX
blocks sprinkled throughout the document?

------
biggestlou
I implore you: do not use anything but Markdown in environments where software
engineers will be writing and maintaining the bulk of the documentation. I
once worked on the docs team for a large org that used rST/Sphinx. Engineers
complained incessantly and it was a constant struggle to cajole them to keep
docs up to date.

My experience suggests unambiguously that engineers will not take the time to
learn a different markup format. They will spend hours or days or weeks
learning a new language, deployment tool, protocol, library, etc. But in most
cases they will simply refuse to spend one iota of time learning documentation
tools. If you think I'm wrong, try making it your day job to get engineers to
write rST (or Asciidoc or anything they don't already know).

~~~
fcurts
Asciidoc(tor) is far easier to learn, read and write than RST (I have
extensive experience with both). Our developers love it. We use it together
with Antora, Asciidoc's answer to Sphinx.

------
ceejayoz
> What if you want to have some things in the documentation be colored blue?
> You can’t!

Maybe that's good, though. "Blue" isn't semantic, either.

------
ComputerGuru
RST is terrible. The idea is great, but the ball was dropped on the execution.

We switched to restructured text for fish, and I remember the insane loopholes
I had to jump through to render the markdown equivalent of `followed by a
trailing space ` because Sphinx absolutely insisted on eating that trailing
space.. and there’s no way to actually explicitly define an inline code block
so I could bypass the abstraction (whereas with Markdown I could always just
insert a code element).

And don’t get me started on the inability to nest markup. What a joke. You
can’t bill something as a “more legitimate documentation language” when you’re
not even at feature parity with Markdown.

~~~
fcurts
For us, Asciidoc(tor) is the answer. As easy to learn and use as Markdown,
more powerful than RST. Best combined with Antora, Asciidoc's answer to
Sphinx.

~~~
ComputerGuru
I’d seen Asciidoc but not Antora before. I like it, thanks for pointing me
that way. I had also missed the Markdown compatibility shims, which are
useful.

One thing that turned me off of Asciidoc was the dated smart quotes syntax. I
actually wrote my own Markdown preprocessor for LATeX that takes care of smart
quotes, links, bold, and italic and have been using that for now.

------
anonu
Most people will agree documentation is hard and painful. Engineers like to
build and have someone else maintain and support. Im talking in generalities -
so don't get too offended if thats not you.

So it follows that you should reduce the critical path to documentation down
to the path of least resistance. Markdown tools are plentiful. If you use
GitHub, it is the core of their project management tools.

Also, you want documentation to be a "living & breathing document" \- in the
sense that it should be updated and modifiable by everyone. A LaTeX-like
solution doesn't lend itself easily to collaborative work.

------
johnminter
Use what works for you and we will use what works for us.

Markdown is a great tool for documentation, especially using tools like
RStudio and Rmarkdown. These tools typically use pandoc under the hood to let
an author generate whatever they need - HTML, PDF, Word documents, Power Point
slides...

Because Markdown (and the tools mentioned above) produces a text document,
this plays well with version control using git and github. Indeed github
renders markdown files in the browser. These tools have been embraced by
scientists who want to generate reproducible documents.

------
lucideer
I was unconvinced going in, but this is a compelling piece. Not dogmatic, very
open to various alternatives. Highlights their advantages and Markdown's
disadvantages without becoming laborious.

------
stared
_Sigh_. Markdown is "good enough". If it helps writing documentation, it is a
good tool.

What I struggle with is documentations that are incomplete (e.g. miss crucial,
"obvious" installing steps), out-of-date, or incomprehensible. Often external
contributors help (especially newbies), as they look at your project with a
fresh eye, taking nothing for granted.

If for a given project .rst is better than .md, cool. And if you generate HTML
from it, end-users won't care what was your base format.

------
eeZah7Ux
Markdown and reStructuredText are very limited, and the latter is awkward and
unfriendly.

Use AsciiDoc. It scales up to entire books. It's extendable by design.

It supports embedding diagrams, maths & so on.

~~~
kevin_thibedeau
ReST has essentially a 1:1 mapping to DocBook. You can export its internal DOM
as an XML file and XSLT it straight into DocBook. I wouldn't exactly call it
limited. It is also the only plaintext markup with a standardized extension
mechanism when it doesn't do what you need.

------
kvz
I love Nix but even their core contributors agree the available documentation
and broader information in the form of blog posts and tutorials in the
ecosystem is subpar. I think the refusal to use Markdown and hence profit from
more contributors is a big factor there. Sometimes it’s good to be a purist,
and it has gotten Nix where it is today, but hanging on to ‘superior’
documentation formats can hurt growth and a dash of pragmatism would really
help.

------
gfiorav
It's never the best standard that wins, it's the most convenient.

Figure out how to parse .md (or whatever is the standard) instead of
pretending others switch to your standard.

------
rikroots
Many years ago I made the mistake of documenting my Javascript library thing
by building static web pages to explain it all. They became a nightmare to
maintain, and made me scared to update anything in my library thing because it
meant having to fix the web pages too.

A while later, during a significant recode exercise, I tried a different
solution. Inline code documentation with YUIDoc - which was much better.
Except YUIDoc assumes people are writing their Javascript in an Object
Oriented way. My library thing didn't have a single class in it. The generated
documentation just didn't make sense ... but by the time I realised this I had
almost completed the documentation exercise and wasn't going to waste the
work. So I also updated the static web pages too (finally!) and presented both
sets of documentation on the Javascript library thing's website.

The thought of having to document changes and updates in two sets of
documentation stopped me working on my Javascript library thing for over TWO
years.

Last year, when I made the decision to rewrite my Javascript library thing
from scratch, I also made the decision to dump all the documentation. Instead
I wrote it as inline comments in simple Markdown - the most basic flavour
available - and used a tool to auto-generate documentation from that (I've
ended up using docco - it does the job).

Dumping all the documentation baggage has made me massively happier, and given
me renewed love for working on my Javascript library thing.

... As for project runbooks? I write them in Google docs. If a client ever
demands to see their project's runbook (please God no!), I can create a PDF of
the latest version and email it to them.

------
myu701
I agree with the limitations of Markdown re: it being not great at doing some
quality of life things like same-document references or embedding images as
base64.

I would enjoy those two features, can we add 'em? MD files would basically be
able to replace RTFs in all but the older OLE stuff in the latter.

But...even though I wish for those two, I have some sense that these things
would start us down the slippery slope of bloating markdown to be HTML
2020(TM)

~~~
roblabla
> embedding images as base64.

That's already possible with data URL. You can easily do
`![alt](data:image/png;base64,<base64 png here>)`.

Now, this won't work on GitHub due to security restrictions (you could embed
an SVG that contains a script). But Markdown/CommonMark supports it just fine.

------
yellowapple
> Kidding. LaTeX is extremely powerful but also a nightmare to use and almost
> impossible to turn into online documentation.

htlatex: "Am I a joke to you?"

\----

I can't really speak to either rST or AsciiDoc (since I don't use either of
them nearly enough to be comfortable with their pros and cons), but aside from
LaTeX (via htlatex or Pandoc or some similarly-useful way to export to HTML
for online use), I've also seen POD ("Plain Ol' Documentation") and outright
manpages as effective choices here. Both are designed specifically for
documentation (in the case of POD, _inline_ documentation), and both are
demonstrably able to produce a variety of output formats, including HTML for
online use.

That said, I also don't see why Markdown (or a more robustly-defined version
thereof) couldn't be used to do the things rST can apparently do, especially
when combined with a preprocessor (like what you'd almost certainly be using
when generating documentation from e.g. source code comments like what quite a
few modern programming languages support; on that note, quite a few of those
languages do use Markdown for inline docs).

------
tannhaeuser
Obviously, the best documentation is the one that exists in the first place,
and markdown is a very low-friction way to document things.

That said, FWIW, using markdown vs highly "semantically" structured text
doesn't need to be an exclusive-or choice. Citing from sgmljs.net markdown
(markdown-in-SGML):

> _sgmljs.net Markdown is presented as an application of the SGML SHORTREF
> feature, which is an SGML mechanism to describe custom Wiki or other domain-
> specific syntax. Whereas in regular markdown it 's possible to use HTML
> markup, in sgmljs.net Markdown it's also possible to use SGML markup and
> other constructs, bringing SGML's vast facilities for text organization and
> processing to markdown in a natural way. [1]_

For example, to annotate HTML's text spans semantically with RDFa or whatever,
add context-dependent CSS classes, perform transformations, define custom
syntax on top of markdown, customize markdown flavours such as github's, use
text macros, add page boilerplate, etc.

[1]:
[http://sgmljs.net/docs/markdown.html](http://sgmljs.net/docs/markdown.html)
(my site)

------
umvi
Markdown is the best. It's plain-text, meaning it can be version controlled.
You can transform it to other formats with pandoc. It supports most common
formatting options.

I'm sorry, but "no color support" is not a compelling reason to switch to
something more complicated. Define your own color meta-tag and generate a PDF
from the markdown with colors if you care that much.

------
BeetleB
I used to think rst was a great solution. It is in many ways better than
markdown.

Then I tried using it. For a few years. To be honest, while certainly better
than LaTeX and HTML in terms of ease of typing it still felt like typing with
road bumps.

These days I just use orgmode and then use pandoc to convert to rst for my
Pelican blog. It's not as powerful as rst but at least it's not markdown.

------
bloak
One of the many things that annoy me about Markdown is the complexity of
generating it and the difficulty of converting a Markdown document into a
normal form. However recently I stumbled across this project:

[https://github.com/bobertlo/vmd](https://github.com/bobertlo/vmd)

I've not tried it, but it sounds interesting.

------
paulsutter
Good documentation is whatever actually gets written. This reminds me of all
the “semantic web” dreams that never happened.

> Good documentation is all about the semantic markup. A “definition” is not
> just a different formatting or like. It means there’s actually a concept of
> a “definition” as a discrete concept in your documentation.

~~~
criddell
That section stood out to me as well. Semantic markup may be useful, but it's
not _the_ defining characteristic of good documentation.

------
jkingsbery
As others have said... if you have extra time to optimize how you write
documentation, fine, but just get something written. Actually... if you have
extra time, take the time to write your documentation _well_ \- make it clear,
consider who the audience is, spend some time thinking about how to organize
the information, and so on. If you _still_ have extra time, then it's time to
worry about latex vs. xml vs. html vs. plain text vs. Word vs. Wiki vs. RTF.

The company I work for has a wiki that most teams use for documentation, and
that generally works pretty well - for most uses, you can use the WYSIWYG
editor, and if you need something more precise you can use the wiki text
editor.

------
Niksko
The answer, as always, is that it depends.

If you need to make some scribbles to describe a project, markdown will do.
All of the things in this article are valid, but they're really don't apply to
barebones documentation.

If you need some more formatting and bells and whistles, then you graduate to
something that supports macros and a is a more fully fledged tool (eg. Hugo).
These tools solve these problems, while (generally) keeping the user-
friendliness of markdown. At least if you build some sort of complex behemoth
of a publishing system with macros and custom styling and all sorts of things,
if somebody needs to make a small content change, you using markdown will be a
saving grace.

------
d_burfoot
I don't have a strong opinion about the base format, but one of my strongest
technical opinions is that all documentation should be computable - that is,
it should be generated by a program that's linked together with the code it's
describing. You should reference particular code structures in the docs, and
if the docs gets out of date it should _break_ so that you're not lying to the
reader about what's going on. Depending on how deep you want to go, you can
also interact with the base code a bit in the doc-generator, showing
particular input/output results, or show a few records from a DB table, etc.

------
manigandham
Any documentation is better than none, so whatever is easiest is the best. And
currently that's Markdown. RST isn't even close.

Most projects don't need anything more than the headings, lists, paragraphs,
and code-blocks anyway.

------
simias
I thought that the author would make the case that technical doc should we
written in some semantic format that could then easily be re-processed for
various use cases which I could sort of understand (although any doc is better
than no docs, so if Markdown helps with that I'm all for docs.md).

But "my markup language is better than your markup language" is not very
productive IMO. The fact that markdown lacks some advanced formatting tools
might even be considered a feature, it means that it will render correctly
when converted to monochrome output for instance.

------
threatofrain
How about MDX (Markdown + JSX)?

[https://mdxjs.com](https://mdxjs.com)

[https://github.com/mdx-js/mdx](https://github.com/mdx-js/mdx)

------
jasonv
Anyone have recommendations on how to write a really structured book? I've
been working on a text and I really want each section of chapters to be
formatted identically, but also be editable, so that I can edit the chapter
definitions, re-publish and merge with content I've already been working on.

Sometimes I go into a tool like Airtable to define content pieces, but there
are a lot of pieces.

What I'm looking for is a way to define a chapter/sub-chapter recipe and work
on iterative changes to content even as I refine the recipe definitions.

~~~
bjoli
now, I am an old fart. you shouldn't really listen to me, but here it goes:
XML and xslt.

I have been using it with SSAX (XML and the scheme programming language,
married in harmony) since 2005. It allows for structured documents that can be
validated against a doctype in milliseconds and you can output whatever
formats you wish.

I made a "documentation" doctype in 2005 and has used that to output
documentation in whatever format I wanted (html, plain text, latex, markdown).
Sure, it requires you to write XSLT or scheme using SSAX, but at least it will
be your own fault whenever the tooling falls short.

my personal website is written XML, and generated server side using guile
scheme and SSAX. I have been laughing quietly to myself every time people
complain about the shortcomings of whatever markup their static site generator
uses. Whenever I have had a need for something else, I can quickly edit my DTD
in a backwards compatible way and add whatever sxslt transformations I need.

All that editing of HTML3.2 in notepad.exe made me immune to the ugliness of a
light XML markup.

~~~
emmanueloga_
Nice! I think it is not chance that XML and Lisp pair so well. After all, XSLT
evolved from DSSSL that was based on a subset of scheme! [1]

I've been using XSLT3 with Saxon-HE [2] + Clojure these days and I'm quite
enjoying it. I use RelaxNG for validation (may sprinkle a bit of Schematron in
the future).

Another pairing of XML and Lisp that I remember is Qexo [3].

1:
[https://en.wikipedia.org/wiki/Document_Style_Semantics_and_S...](https://en.wikipedia.org/wiki/Document_Style_Semantics_and_Specification_Language)

2:
[http://saxonica.com/products/products.xml](http://saxonica.com/products/products.xml)

3: [https://www.gnu.org/software/qexo/](https://www.gnu.org/software/qexo/)

------
binarycrusader
The wonderful markdeep addresses many of the author’s concerns:

[https://casual-effects.com/markdeep/](https://casual-effects.com/markdeep/)

------
gjvc
I'll use whatever I damn well please. Don't tread on me!

------
lajr
I think the limitations of markdown make it great for README documentation. It
allows uniform, easy-to-parse instructions on how to use any repository. I
don't even necessarily agree in terms of full documentation sites. Services
like Gitbook or libraries like Gatsby allow you to set up great documentation
sites using markdown. The points made about each unique syntax requiring it's
own parser doesn't seem like a significant obstacle to me.

------
glofish
I tried reStructuredText and I found that writing hyperlinks was very tedious
and ugly. Here is the example from the tutorial

    
    
      External hyperlinks, like `Python <http://www.python.org/>`_.
    

Look at how many special characters it needs and how interferes with reading.

I found it annoying and tiring to write and to read. It is the main reason I
went with Markdown.

RST may be superior technology-wise but it inferior when it comes to usability

~~~
fcurts
I had the same gripes with RST. Then I found Asciidoc(tor) and never looked
back. Asciidoc is as easy to learn and use as Markdown and more powerful than
RST. Best combined with Antora, Asciidoc's answer to Sphinx.

------
anderspitman
While making my blog browsable with curl[0] recently, I realized that I
haven't been appreciating the human-readable aspect of Markdown. Text-heavy
content doesn't always need another layer of abstractions (HTML/CSS/JS), nor
the huge dependencies that come with them (browsers).

[0]
[https://anderspitman.net/17/#curlable](https://anderspitman.net/17/#curlable)

------
k__
Back in the days we used DocBook for documentation, because it's medium
independent.

When I read that AsciiDoc is a Markdown-like syntax for DocBook, I was
instantly sold.

------
dmitshur
I’m glad there are some languages that define a simple convention for writing
documentation as comments in code directly above the symbol, and tools for
automatically extracting and displaying that documentation.

I prefer knowing where to look for documentation in any project, rather than
having to guess where some Markdown or HTML or RST files might be, separated
from code.

------
ashildr
I and my team use two tools for documentation: \- markdown (+ plantuml),
because that’s plainext with not enough rules to bother them and keep them
away from what they actually want to do. And it can do tables. \- LaTeX,
because if you already decided to do it properly and put away the IDE you can
use the _big_ tools and not something in between

------
nobodywillobsrv
What I really want is a Makefile that is also Markdown.

So something with runnable (singleton) entry points and some english sentences
giving context.

This is what I typically do for small experiments that I will completely
forget about.

Too many IT folks do work and leave the running-entry-point and build-dev-loop
as secret shadow workflows. It is basically fraud or stealing if you are an
employee.

------
markus_zhang
To be serious, anything but Confluence. I have had enough with that and have
to continue endure its existence for many more years. I use RST when I'm
programming in PyCharm (support out of box I think), and use MD in other
places.

BTW I think Typora is a nice MD tool as it supports copy-paste of screenshots,
extremely useful when writing tech documents.

~~~
Noumenon72
Confluence is what I was thinking of when he was talking about cross-
reference! Paste a page link in and it continues to work even when the page
moves or is retitled. Embed a section of one page in another page. Macros that
collect all pages with certain parents or properties. I adore Confluence and
it _is_ semantic -- header levels, "tips" vs "warnings", and expandos to
signify "stuff you don't need to read right now".

------
savh
Obviously well written documentation is never easy and documentation format
also depends on use case. For most of my needs Markdown is good enough. It's
easy to learn, easy to use and well supported.

I like to think that its simplicity (or lack of features) forces me to just
focus on simple text to write easy to understand documentation.

------
arkanciscan
Please don't write long articles about why people shouldn't do something you
don't like on the Internet.

------
rs23296008n1
Mixed feelings about markdown. I think its great but the number of dialects is
likely a possible issue. Perhaps a linter or sanity checker is required?
Tables are an example, but no reason to dump markdown.

But I'll still write markdown since its easy to generate and relatively easy
to transform into a lot of something else.

------
madsbuch
I wrote my entire thesis using markdown as a super set of latex. I agree with
the sentiment of the article, that for efficient documentation you need for
building blocks. But I am still very happy about using markdown as a super set
of other markup languages (HTML, latex, etc.) for friction less prose writing.

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

~~~
lioeters
Here's a reformatted version:

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.

------
turbinerneiter
Pandoc solves most of the shortcomings of markdown. I've written papers and
Thesis with it. The main problem is that it isn't standard and some missing
features need additional plugins. So your pandoc-flavourved markdown doesn't
properly render in GitLab/GitHub.

------
jacoblambda
I went into this article fully expecting to disagree but I think it makes a
valid point. Plain Markdown definitely has issues that cause me to gripe to no
end. These however are mostly resolved via extensions. The author argues that
Markdown isn't a good choice since it lacks these features without modifying
the standard however I don't think extensions are too big of an issue.

If the extensions are part of the build script for processing the
documentation then ultimately the user and consuming developers won't notice
the difference between this and using another markup language.

Hell one of the documentation pipelines I see quite often is the Doxygen +
Breathe + Sphynx pipeline. This handles the markdown and offers most of those
extensions mentioned by the author out of the box.

If your documentation pipeline works well and the user can't tell the
difference, there's no reason to switch. Markdown works and is more elegant to
write in than LaTeX and rST by just about every measure in my eyes.

One last note is that every markup language has it's own special blemishes and
issues. LaTeX and rST are very much not immune to this and when it comes down
to it, a properly built doc pipeline will cover these up no matter the
language.

TL;DR: If Markdown is making your life difficult it's probably not Markdown
that's broken, it's probably your documentation pipeline.

------
opless
If you're worrying about what format you're writing documentation in, I'd
offer the actual motive is that rather than actually writing documentation
you’re finding excuses not to write it.

Just write a text file.

Pretty it up when you’re trying not to think about a problem that you’re stuck
on.

------
hn_throwaway_99
I feel like an analogous discussion could be "please don't serialize your
objects as JSON". But for all its warts and shortcomings there is a good
reason JSON has become the format of choice in many domains. The same can be
said of Markdown.

~~~
sidpatil
I believe that "worse is better" can answer a lot of these questions.
Convenience and simplicity are highly attractive.

------
david_draco
rst is great because there are tools to handle it installed already on many
Linux distributions, such as: rst2html, rst2latex, rst2man, rst2odt ...

Many tools that support markdown actually also support rst. For example, write
a README.rst on github instead of a README.md.

~~~
oefrha
> rst is great because there are tools to handle it installed already on many
> Linux distributions

By that logic I’d recommend writing your documentation in groff or mandoc.

------
nilsandrey
Please, write your documentation in whatever tool you like, including
Markdown, and being Markdown better than others like a word document or
directly PDF for accompanying code. If it's about a code, better living with
him in the same repo.

------
cestith
I tend to use POD, but that's from many years in the Perl ecosystem and the
tools like pod2man and pod2html that make it so easy to convert. LaTEX or
AsciiDOC - or, heck, XML or SGML or DocBook - also work if you need semantic
data.

~~~
_sbrk
Heck, even groff_mdoc works very well.

Whatever you use, document!

------
tunesmith
I started switching from markdown to asciidoc for my code project
documentation, and it was much easier than I expected. For simple docs it's
almost exactly like Markdown, _and_ its IntelliJ plugin is better, too.

------
the_arun
When we say documentation, it depends on what kind of documentation it is.
IMHO Markdown is perfectly alright for API documentation. But are there better
tools for that? I'm finding Sphinx is an overkill.

------
emmanueloga_
I agree markdown is not great for documentation. I'm writing a little site
generator for my blog and after exploring a a lot of different options I
decided to come up with my own format!

XML is a great way to write structured documentation. It is the best option
for "mixed content", that is, content that has character data, optionally
interspersed with structured elements. The problem is that most standard XML
documentation formats (docbook, dita, etc.) are heavy and most times overkill.
I'm using RelaxNG [2] to create a schema of my custom format document [2], and
a bit of XSLT3 [3] to generate HTML5.

RelaxNG is great, and pretty easy to use. You can think of it as a "regular
expression over trees". The syntax is pretty intuitive, specially the compact
form (there's an XML form too). For instance:

    
    
        start = element doc {
          attribute title { text } ?,
          element p { text } *
        }
    

... defines the schema for a document that should have a "doc" root tag, an
optional title attribute, and 0 or more "p" elements, that should contain only
text.

The way I went about it, I'm just inspiring my format in a small subset of
HTML5, plus some tags that I want to use to provide more structured
information.

XSLT 3.0 came a long way since the version 1.0 that everybody remembers and
loathes. Now, XSLT3 has maps, arrays, functions, higher order functions, and
all sort of other goodies that people have come to expect from a modern
programming language. Yeah, you still need to get pass the XML syntax, but it
is not a big deal once you get the hang of it.

Finally, writing XML "by hand" is not a big deal neither. I'm using Emacs with
the nxml and emmet [4] package, and I just needed to learn a few keystrokes
for doing things like automatically closing tags. Emmet is amazing and fun to
use to create small chunks of content at a time.

1:
[https://en.wikipedia.org/wiki/RELAX_NG](https://en.wikipedia.org/wiki/RELAX_NG)

2:
[https://gist.github.com/EmmanuelOga/39ddb345c2a499690e728e59...](https://gist.github.com/EmmanuelOga/39ddb345c2a499690e728e5908e942f2)

3:
[https://stackoverflow.com/tags/xslt-3.0/info](https://stackoverflow.com/tags/xslt-3.0/info)

4: [https://emmet.io/](https://emmet.io/)

------
Skunkleton
I would rather have markup free documentation than no documentation at all.
Many of the documentation markup languages have a pretty significant overhead.
There is a reason markdown is so common for docs.

------
tbergeron
This place is becoming a meme of itself more and more each and every day.

~~~
gjvc
I think you might mean "parody".

A parody is an imitation of the style of a particular writer, artist, or genre
with deliberate exaggeration for comic effect.

A meme is an image, video, piece of text, etc., typically humorous in nature,
that is copied and spread rapidly by Internet users, often with slight
variations.

(;-))

------
samsquire
I've written a flat HTML renderer.

[http://github.com/samsquire/flat-html](http://github.com/samsquire/flat-html)

Could be an alternative to HTML and Markdown

------
Guthur
We all know it's XML but everyone is too scared to admit it.

It's simultaneously the best and worst tool we have for structured
semantically rich information. And unfortunately probably the only one.

------
movedx
I’d say my website, which is a growing knowledge base for CloudOps related
matters, works really rather quite nicely:
[https://thecloud.coach/](https://thecloud.coach/)

Thanks to MkDocs and the Material theme, as well as plugins and extension,
this whole setup looks great and scales really well to any device.

I think the author’s article speaks purely to documenting code. I’d say code
is much harder to document and I think I’d agree even MkDocs (and the setup
I’m using) wouldn’t be good for pure code documentation. But documentation for
a project?

Nah. You’re completely wrong on this one.

Edit: down voting without providing as rebuttal is childish, at best.

------
jason_slack
As a technical writer, I write everything in Markdown.

Sure, it could use some features.

Does anyone know how a developer could contribute to the markdown standard and
code up some desired markdown features?

------
jeffdavis
It's two different philosophies of publishing. Markdown mixes style with
meaning. Something like latex separates meaning from style.

------
sagichmal
> Markdown is about formatting, not information

> Not extendable

> Local processing only

> HTML Only

I don't get it. These are all extraordinary virtues of Markdown, not
negatives.

~~~
dalai
Virtues when writing comments on HN, blog posts, READMEs or whatever. When you
are writing non-trivial, lengthy technical documentation, at some point you
may need markup for examples, notes, tables, figures, cross-references,
function parameters, class methods, etc. Sure you could still do something
like that with basic markdown, but you would need to write down all your
conventions somewhere if you are not working alone. At that point you could
just use whatever comes with those conventions baked-in.

------
dbg31415
Hey, do you know how few projects have good documentation? Or any
documentation?

Write it in whatever you want to write it in, just write it.

------
phy6
Beware of things that are fun to argue.

------
l0b0
Reality check: what is your budget for documentation? "As little as possible"
says the vast majority. OK then, Markdown it is. For anyone else, sure, spend
a few days setting up LaTeX to actually produce PDFs (no, PostScript is not
end user friendly) and a few weeks duplicating the Markdown you already knew
how to write because you know ASCII formatting and basic HTML.

------
mnot
And yet, many RFCs are written in markdown now. And variants like kramdown do
support semantic markup.

------
schnable
I almost closed this page when he suggested LaTeX. Glad I read the next line
:).

------
teknopaul
Pfff. Imagine the state of the github if everybody wrote documentation in
HTML.

------
AzzieElbab
Markdown, shmarkdown. Just write some documentation please.

------
paol
TL;DR Don't use Markdown, use RST (reStrucruredText)

My take: meh.

RST is very comparable to Markdown, and the article makes almost no mention of
why it is better. There is a downside, that it has a learning curve because
most people are not familiar with it, whereas almost everyone has already used
markdown.

~~~
marcosdumay
Besides, all the good tooling for RST is in Python. So if your project does
not use it, it's yet another language.

Markdown is supported everywhere.

------
throwaway3563
Please don’t tell me what not to do, it’s considered harmful.

Especially please don’t tell me to ignore an industry standard only to offer
some bespoke solution as an alternative.

~~~
gridlockd
To be fair, he was asking nicely - begging even!

RST and Sphinx _are_ "industry standard". Markdown isn't really a standard at
all, nobody uses the plain version, everybody uses informal extensions.

I think starting out with Markdown is fine and if it becomes unmanageable, one
can still migrate to RST.

------
mcguire
Tl;dr: " _Good documentation is all about the semantic markup._ "

Well, ok, I'll buy that.

" _What to use instead: LaTeX. [Just kidding.] A better answer is
reStructuredText or RST. [Or AsciiDoc.]_ "

Er, well, ... RST does have extension syntax that allows you some flexibility
to use semantic markup, but then the tools all have to understand the
extensions you use. LaTeX at least has the ability to define the meaning of
your extensions in its own syntax, but that is not all that much fun.

Conclusion: Everything sucks. Sorry.

------
jasonmp85
Counterpoint: no.

------
jhokanson
Thanks i

------
exabrial
The only problem I see with markdown is the lack of an IETF spec. But then we
run into the XKCD problem...

------
brian_herman__
Please don't make platitudes and decisions for everyone.

