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.
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.
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.
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:
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.
> 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.)
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.
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.)
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?
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!
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).
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/
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.
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)
That's already possible with data URL. You can easily do ``.
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.
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.
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.
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) 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)
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.
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.
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).
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.
Remember how we’re always saying to keep it simple here? Well, documentation is no different. These tools are very painful to work with. Stuff like sphinx will make you want to tear your hair out.
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.
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.
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).
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.
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.
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.
> 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."
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.
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.
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.
219 comments
[ 3.2 ms ] story [ 279 ms ] threadMy 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.
Markdown is supported everywhere.
https://www.python.org/dev/peps/pep-0287/
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/exam...
Markdown has a lot of implementations (with some fragmentation, granted) and is adopted by many diverse projects outside the python sphere.
Pandoc supports rST.
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 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.
Hint: This is rhetorical. https://docutils.sourceforge.io/FAQ.html#is-nested-inline-ma...
> 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:
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'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.
= - ^ ~
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:
(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.)ReST for life!
Please learn to use and love pandoc
https://casual-effects.com/markdeep/
The most important property of documentation is existence. Markdown has a low barrier to entry and the markup can later be upgraded to Asciidoc.
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
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)
That's already possible with data URL. You can easily do ``.
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.
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/#/
Maybe that's good, though. "Blue" isn't semantic, either.
"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...
If you have such a person anyway, you can just let other contributors write simple text without any styling to begin with.
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)
Granted, that's only a weak argument against Markdown. I rarely encountered converters that would work 100% correct for any given textual format.
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 only two markdown features afaik that work on HN are italics with asterisks and code blocks with 4 spaces.
That's it.
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.
Many tools that support markdown actually also support rst. For example, write a README.rst on github instead of a README.md.
By that logic I’d recommend writing your documentation in groff or mandoc.
Keep it simple- markdown is simple.
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.
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).
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.
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.
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.
I apologise to anyone who ever has to read my documentation. I'm really, truly, sorry. I have excuses but no reasons.
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.
> 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.
What processes or tools do you know of to keep documentation up to date as code and environment change underneath it?
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.
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 :)
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."
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 :)
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.
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.
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.