Don't write documentation in Markdown | Hacker News Reader

Don't write documentation in Markdown

buttondown.email

286 pointsrandyzwitch211 comments

Concurrent rebuttal thread: https://news.ycombinator.com/item?id=22677970

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

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.

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/

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

> It doesn't appear to me that the article linked in the rebuttal thread appears to address any of the points made in this article.

The arguments are weak to mind boggling, and the technical nit-picking would better addressed by suggestions on how to support those minor features in markdown.

It makes absolutely no sense to complain about the document format when commenting on documentation.

> It makes absolutely no sense to complain about the document format when commenting on documentation.

Why not? When aren't formats important? Or is it the fact that it's documentation that makes it not worthwhile to comment on?

There is lots of plugin support for markdown that the article doesn’t consider. I actually wrote some documentation in markdown that used a plug-in to embed markdown generated flow charts and then exported to PDF to create portable documentation. The article makes decent points but there’s no wrong or right answer it’s situational.

Plugin support for a bad idea doesn't make the bad idea better.

Why not? Lots of crappy products have been improved tremendously by third-party plug-ins.

"Bad executions of an idea" is very different than "a bad idea"

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

Then you still need somebody who cleans up the documentation afterwards or converts it into your Markdown dialect of choice.

If you have such a person anyway, you can just let other contributors write simple text without any styling to begin with.

1) Due to natural inertia there exists to leave things alone that aren’t overtly broken, I doubt there would be a lot of cases in which people would feel so inclined to convert to a different format

2) If people do need to convert it, at least it’s a simple enough spec that conversion shouldn’t require a Herculean amount of effort (I bet there already exist converters that others have written)

As Markdown is available in a plethora of dialects, it's likely any given converter doesn't work 100% correct with the dialect at hand.

Granted, that's only a weak argument against Markdown. I rarely encountered converters that would work 100% correct for any given textual format.

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

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

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.

The backslash\ may qualify, and it’s part of the standard.

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

> 2 spaces at the end

I prefer just plain "<br/>" because it does not mess with my editor configuration, which otherwise I have to constantly tweak between "strip all whitespace at the end of line" and back.

I like it, as it lets me format at 80-char breaks to prevent infinite line lengths for paragraphs of text. This makes Github diffs easier to read as well.

except when you add one word and re-flow the entire paragraph

Your editor should be able to help with that. For example in vim: `gqap` will reflow the current paragraph, or while in visual select mode you can use `gq` to reflow your selection).

This still ruins the diff view of the code, though. (e.g. git blame)

that's exactly what causes the viewing diff problem that I was replying to

--word-diff=color is your friend in this case.

That's when semantic line-breaking comes into a picture. Put a line break before each new sentence and before each clause in a sentence. That makes the text much more diff-friendly, and tends to keep the line lengths at bay too.

To pile on a +1 for this: I've seen a huge increase in basic documentation after switching from RST to MD. 5x or more. Highly-crafted docs are indeed better in RST (or some other rich system), but it's also a huge turn-off for random contributors due to its unfamiliarity and verbosity.

Agreed! Every time I need to do something in markdown I just pull up a cheatsheet and start typing. It's so simple that it fits on a page and I don't even feel like I have to learn it to use it. Markdown works for github README.md. It works in Trello. I have it on my blog that I update once a decade. I don't find the argument to stop using it persuasive at all.

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.

Right. The author kind of sets him up for this point by joking that LaTeX would be better, and then walking it back.

Of course you could write docs in HTML with CSS if you wanted perfectly expressive syntax highlighting and context demarcation. And the opposite end of this would be arguing to use raw plaintext like an IETF specification.

But really Markdown is ubiquitous and represents a usable compromise between being readable as plaintext while enabling the 'progressive enhancement' of being converted to HTML.

Fun fact: many IETF documents are written in Markdown now and converted to the other formats you are used to.

Reading this and thinking of the dozen .md documents in my repo that are sooo badly out of date they're actually misleading.

I apologise to anyone who ever has to read my documentation. I'm really, truly, sorry. I have excuses but no reasons.

Could you please share your excuses, so we can all use them? :)

I do feel for you :) but at the same time I think Markdown, the tool, is not to blame for this.

I write most of my documentation in Markdown or just plain text files. The reason is simple, I want the same focus that I had when writing the code. Doing a context switch from code/IDE to html/Web is a nightmare for me. If that would be mandatory for some reason, my documentation would suffer from more bitrot then it does now.

I agree 100% with your sentiment:

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

Just so long as you remember who is supposed to be reading it, and ensure that they can. What language you use to structure it is more a question for you (and your team), and matters much less.

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?

Keeping docs and code as close together as possible. Certainly same repo. But for instance one of pythons greatest feature is docstrings. Which has encouraged documentation in the code. Other than that document in comments. And things like openapi and sphinx to generate docs from code.

Low level docs such as foo() does x and raises error when y should be expressed as unit tests.

External to code docs should be limited to things like deployment process.design docs (part of point of which is their history should be versioned not changed.

Proximity is a big help, for sure. Cross-references, ideally checked mechanically, can be helpful in making things proximate to multiple points.

I very much agree with expressing assertions as tests. Doctest is an interesting point in the space, here. An idea I've had (and prototyped, but never quite got where I wanted) is a system where I can add references to tests as citations supporting claims in documentation, such that when the test fails the assertions it supports can be surfaced.

Also, documentation that is frequently used is typically thereby checked against reality, and necessary updates found quickly. But much documentation won't be sufficiently frequently used to rely on that.

There are many things that help. I'm always looking for more. Thanks for your input :)

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

Very interesting proposal.

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.

Shameless self-promotion: That was exact problem I was facing during my entire career. That's why we decided to build a tool which links documentation and code -- https://nots.io This gives at least two benefits: now it's easy to find the right doc straight from the code you're working on. Also Nots tracks updates in code behind each doc, and marks the docs as obsolete if code has drastically changed.

Would up vote 5x ... Thing is "documentation nerds" are quite sparse and most people don't give a f. Going easiest way is the way to have documentation up to date.

If someone wants to make it perfect so be it, let that person do it all. Then every change is left to such individual to be done and then guess what what happens when he is the person that has to do ALL the changes for documentation. Probably he won't have time to do more interesting things :)

I don't think the author misses that particular point. It's just that the author's goals are obviously different and way beyond just having documentation apparently. I mean, quote:

You should be able to hide all the definitions if you want or show only the definitions. You should be able to mark several code samples as doing the same thing in different languages. You should be able to generate the documentation with and without “TODO” sections, so you can share separate versions internally and externally

When I read that I was like 'wtf is this about'. For someone who barely has any documentation at all usually (me) this seems next level. But thinking of it this actually makes sense and I totally understand that if you're at the point where you want to apply those things you likely have a ton of ducumentation and perhaps don't need being pointed out that the main goal is writing it and you're most likely right in saying that markdwon is not the correct tool for that job.

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

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

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

Currently having this fight - "The code is the best documentation!" has been the answer to my "where is all the documentation?" question. Sure, except there's 2100+ source files spread over 120+ Go packages encompassing 4+ years of development before I arrived. I'll be right back and productive after 2 years of wading through this, ok?

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.

Totally agree. rst is feature-rich but very difficult to get right. You practically need the documentation open at all times. I would rather write (and read) documentation in txt, with links as footnotes.

Yep. Was going to say the same thing. IMO Sphinx and rst is a bad experience. Markdown _is_ simple—that’s what is great about it. I’m also a fan of languages that support markdown in comments/in-source-documentation (rust, elixir, etc.)

Not only that, but elixir docs will automatically search markdown for appropriate content in backticks and hyperlink corresponding code (in elixir STD lib, erlang std lib, and I believe dependencies) for you. That's much harder to do in rst.

Worth noting that the de facto markup in python docstrings is RST

https://www.python.org/dev/peps/pep-0287/

You can also use the Google style [1], which we do because it's not RST so it's actually readable by humans.

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/exam...

But rST is deeply linked to python: as far as I know the only existing implementation is in python, the touted "extensibility" is based on python, etc. Other languages don't seem to adopt rST because they don't have this deep relationship with it.

Markdown has a lot of implementations (with some fragmentation, granted) and is adopted by many diverse projects outside the python sphere.

> as far as I know the only existing implementation is in python

Pandoc supports rST.

I mean look if you want to compare overall python doc quality vs elixir doc quality (especially for community projects)...

I write Elixir docs on my projects because it's easy pretty and obsessively making my docs prettier hits that spot in my brain.

Extreme example:

https://hexdocs.pm/zigler/Zigler.html

Where I've automatically marshalled zig code into the elixir documentation (https://hexdocs.pm/zigler/beam.html#get_f32/2) and you can click the slash in the upper right of the function header to link to the code on Github.

As a bonus, check it out on mobile and compare it to this on mobile:

https://docs.python.org/3/library/functions.html

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.

Please enlighten me on how to produce [`code`](https://example.com) in reST.

Hint: This is rhetorical. https://docutils.sourceforge.io/FAQ.html#is-nested-inline-ma...

I saw your other comment as well. I don't know what to say, you're correct, RST is deficient here.

Is there a syntactical reason this method couldn’t be supported in rST?

No. Quote FAQ:

> Not currently, no. It's on the to-do list (details here), and hopefully will be part of the reStructuredText parser soon. At that time, markup like this will become possible:

  Here is some *emphasized text containing a `hyperlink`_ and
  ``inline literals``*.

So absolutely valid syntax just doesn’t work. Aaaand that todo list entry dates back to 2001.

(I know, I know, instead of complaining I should submit a fucking patch. Unfortunately fixing reST is one of the least urgent things on my should-submit-a-patch list.)

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

I countb at least 5, from memory.

= - ^ ~

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

Just the opposite. Hate the markdowns.
ReST for life!

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.

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.

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

Yeah, I would rather invest my effort in “make your config files yaml, never json (because comments and ergonomics)”, which seems parallel and much more important.

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

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

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

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.

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

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

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

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/

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.

It might be possible via custom roles.

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

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

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
- [1] https://github.com/karlicoss/rexport/blame/master/README.org...
- [2] https://github.com/karlicoss/cachew/blob/master/README.ipynb
- [2] https://github.com/karlicoss/cachew#features

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, for an org-mode experience out-of-the-box.

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.

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

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.

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
[1] http://python-forge.rtfd.io/
[2] https://github.com/dfee/forge
[3] https://dfee.github.io/rbx

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

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.

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.

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.

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.

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

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

We use quite a bit of markdown at Stripe :)

I was at a conference once that was mainly sales pitches for cryptocurrency startups. Most of the people were very polished, but one guy was clearly a developer who had been pressed into service as a presenter. In the middle of his presentation he started talking about how great the documentation for Stripe is. That's got to be some damn good documentation.

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.

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.

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

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?

I beg to (partially) disagree... (shameless plug ahead!)
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.

My blog dives into Markdown, Pandoc, R, bash, and the ConTeXt typesetting engine.
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
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
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
My open-source editor, Scrivenvar (https://github.com/DaveJarvis/scrivenvar), implements that architecture to some extent.

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

...Org mode anyone? https://orgmode.org/

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

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.

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

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.

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.

I am trying to write a layout engine that is TMWYW.
https://github.com/samsquire/additive-guis

That is pretty cool!

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

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

Post could be reworded:
Please learn to use and love pandoc

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?

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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)

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

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

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 (my site)

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.

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.

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
I've not tried it, but it sounds interesting.

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.

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

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.

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.

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.

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.

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.

How about MDX (Markdown + JSX)?
https://mdxjs.com
https://github.com/mdx-js/mdx

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.

A traditional word processor can do a decent job of that, e.g. LibreOffice.

Look into Simplified DocBook or O'Reilly Pseudopod.

LaTeX is a pretty good fit for this. If you're sticking close to an existing document class, it's very easy to use and will probably look decent without much effort.
However, it can sometimes be very frustrating to get something exactly how you want it. You move this \mbox and it bumps something else, which gets moved into something else, and so on until your desk has an imprint of your head.

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.

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...
2: http://saxonica.com/products/products.xml
3: https://www.gnu.org/software/qexo/

ebookc should cover your needs [1]. It can output a bunch of different formats, including HTML and PDF.
1: https://www.xmlmind.com/ebookc/

The wonderful markdeep addresses many of the author’s concerns:
https://casual-effects.com/markdeep/

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

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.

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

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.

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

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.

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.

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

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.

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.

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

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.

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

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.

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.

Amount of documentation (comments) still seems to be an open question.
e.g. Bob Martin (Clean Code) wrote: > A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail. > https://mobile.twitter.com/unclebobmartin/status/87031189854...
I use to be proponent of comments throughout the code. But lately, am leaning more and more towards minimization through proper naming, annotation, function design (e.g. no side effects, single functionality).
Here are some related materials:
A more complete quote from `Clean Code` > Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation. > > Comments are not like Schindler's List. They are not "pure good." Indeed, comments are, at best, a necessary evil. If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much -- perhaps not at all. > > The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. > > So when you find yourself in a position where you need to write a comment, think it through and see whether there isn't some way to turn the tables and express yourself in code. Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression.
Previous related Discussions on NH: https://news.ycombinator.com/item?id=8073230 https://news.ycombinator.com/item?id=8073620
https://softwareengineering.stackexchange.com/questions/2857...

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.

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.

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.

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.

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.

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

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.

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

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.

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.

Heck, even groff_mdoc works very well.
Whatever you use, document!

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.

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.

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
2: https://gist.github.com/EmmanuelOga/39ddb345c2a499690e728e59...
3: https://stackoverflow.com/tags/xslt-3.0/info
4: https://emmet.io/

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.

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

n-gate.com

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.
(;-))

I've written a flat HTML renderer.
http://github.com/samsquire/flat-html
Could be an alternative to HTML and Markdown

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.

I’d say my website, which is a growing knowledge base for CloudOps related matters, works really rather quite nicely: 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.

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?

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

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

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.

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.

Beware of things that are fun to argue.

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.

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

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

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

Markdown, shmarkdown. Just write some documentation please.

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.

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.

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.

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.

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.

Counterpoint: no.

Thanks i

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

Please don't make platitudes and decisions for everyone.

Reply on news.ycombinator.com