Markdown is an excellent choice for documentation
jeffgeerling.com
jeffgeerling.com
Seriously, checking my post history I've noticed there have been similar posts saying don't use Markdown but use [asciidoc|latex|rst|etc] over and over through the years.
Meanwhile since teams use their own favorite text format, many organizations end up maintaining separate docs for end users in Google Docs, a Word document, or some other system because the non-engineers on the team don't want to spend time learning the ins-and-outs of the special documentation format.
Have I ever ran into limitations with Markdown? Yes.
Has Markdown ever been the reason why things were poorly documented? No.
Whatever gets people to document stuff, and maintain and update that documentation.
But yeah, that would be useful.
These posts read like fluff to me... I was tempted to write a tongue in cheek post titled "Why it is a bad idea to use a butter knife to unscrew a slot screw". Markdown is a tool, it has some advantages and disadvantages, some people will misuse it, but if you can make it work for you, then that's great. It is just a tool.
Yes. Anytime you see technical docs without structure or links to the functions and classes being discussed, it's because of Markdown.
edit: I do use more qualified names, though:
className.methodName or filename.extension:function_name
Asciidoc is fully compatible with markdown, and provides a lot more functionality out of the box.
Basic functionality often needed when writing documentation aren't part of the original markdown spec and require non-standard extensions: tables, footnote, table-of-content, cross references are good examples of this.
The markdown ecosystem is now riddled with non standard extensions and reminds me the browser ecosystem of y2k.
A quick search on Google allowed me to find this page[0] which lists no less than 20 different markdown flavors.
Asciidoc comes in 1 and only 1 flavor that does most of everything you want.
Also, there's a great open-source project that allows you to create a documentation website in Aciidoc: https://antora.org/. (I'm not affiliated, just a happy user)
[0]: https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684b...
> suggests choosing the least powerful [computer] language suitable for a given purpose
is a good guideline. For every "I need feature X" there should be a question if using this feature is actually beneficial. For general typesetting, we can use general XML, with custom tags. Or anything.
To be clear - I don't mean that MD is the solution for documentation. For many things, we clearly need a different tool. For example, for mathematical papers (with many formulae and cross-references) while we can hack MD to do the job, most likely it won't be the right tool.
> Basic functionality often needed when writing documentation aren't part of the original markdown spec and require non-standard extensions: tables, footnote, table-of-content, cross references are good examples of this.
Most of these things, IMHO, are standard solutions, but not as good when you ask why? E.g. instead of footnotes, inline links (it is not printed on paper, is it?), hand-written table are rarely readable as usually other formats are better, you can easily generate TOC from MD headers structure, etc.
Markdown is "good enough" for a large amount of people who care less about what seasoned technical writers care about.
> I just reference other functions by name.
(granted a "function name" isn't the best example): when your documentation becomes large enough, your function name will appear in so many places throughout the documentation that you'll want to change it once in one place, and it to appear everywhere else. Having a dynamic variable inside your documentation to take care of this is immensely useful.
This is the kind of feature that other documentation markups offer that (1) you do not need to use but, (2) have at your disposition when you need to.
Now, just to illustrate this with a better example: I wrote user documentation about "how to create a concourse-ci cluster in Google Cloud". This documentation contains a lot of things specific to my organization ("acme"), for example, the VPC network name that needs to be used is fairly variable and depends on the GCE project name but also the region of the project and other things. Depending on who reads the documentation and their project, a few things need to be changed. For this purpose, the top of my documentation contains a few variables that are then used throughout the document in place of hardcoded values.
The variables:
:concourse-ci-host: ci.acme.io
:concourse-ci-url: https://{concourse-ci-host}
:gke-cluster-name: concourse-ci
:gke-cluster-region: us-central1
:service-account-concourse-ci: {gke-cluster-name}
:service-account-concourse-ci-docker-registry: {gke-cluster-name}-docker-registry
:gcloud-vpc-network-name: {gke-cluster-name}
:gcloud-static-ip-name: {gke-cluster-name}
:gcloud-cloud-router-name: {gcloud-vpc-network-name}
:gcloud-cloud-nat-gateway-name: {gcloud-vpc-network-name}
# Create the network
gcloud compute networks create {gcloud-vpc-network-name}
# Configure the firewall to allow all internal traffic and internet traffic to SSH, RDP and ICMP
gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-internal --network {gcloud-vpc-network-name} --allow tcp,udp,icmp --source-ranges 10.128.0.0/9
gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-ssh --network {gcloud-vpc-network-name} --allow tcp:22
gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-rdp --network {gcloud-vpc-network-name} --allow tcp:3389
gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-icmp --network {gcloud-vpc-network-name} --allow icmp
# Create the network
gcloud compute networks create concourse-ci
# Configure the firewall to allow all internal traffic and internet traffic to SSH, RDP and ICMP
gcloud compute firewall-rules create concourse-ci-allow-internal --network concourse-ci --allow tcp,udp,icmp --source-ranges 10.128.0.0/9
gcloud compute firewall-rules create concourse-ci-allow-ssh --network concourse-ci --allow tcp:22
gcloud compute firewall-rules create concourse-ci-allow-rdp --network concourse-ci --allow tcp:3389
gcloud compute firewall-rules create concourse-ci-allow-icmp --network concourse-ci --allow icmp
Until it's not (example above). And it only becomes not enough when your documentation increases in terms of size, complexity of the subject being documented and number of technical writers writing it.
> My coworkers and my future self are adults and can use ‘find’
But your users don't want to use find. They're already too busy learning and understanding your product and the documentation shouldn't get in their way.
Markdown is fine for quick short documentation.
Asciidoc is needed for extensive large documentation.
For some really serious technical writing, you may need LaTeX. :)
My point is not to dissuade anyone from using AsciiDoc. My point is that I suggest using the simplest tool for solving a gvien problem (documentation writing or a particular project, not for any project).
Ahh, I suspect here is the fundamental disconnect.
I suspect few people reading this are technical writers and don't need the tools which a technical writer would use. When they talk about documentation, my expectation is this is code documentation written by developers to be consumed by other developers, not technical manuals or user documentation.
Cheat sheet: https://powerman.name/doc/asciidoc and there are a bunch of complicated examples on this page: https://www.methods.co.nz/asciidoc/newtables.html
Examples of asciidoc text styling:
'Emphasized text', * Strong text* , +Monospaced text+, ``Quoted text''. 'Subscripts and superscripts': e^{amp}#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^ and ~some sub text~
Example of a nested table (WTF!):
[width="75%",cols="1,2a"]
|==============================================
|Normal cell
|Cell with nested table
[cols="2,1"]
!==============================================
!Nested table cell 1 !Nested table cell 2
!==============================================
|==============================================Here's what I think is a better link[0] than the one you provided. It's the Asciidoc getting started documentation. It's not complicated at all, it looks extremely similar to markdown.
If you want to compare MD and Asciidoc side by side, go here[1]. Which one looks more complicated?
Now, regarding the table syntax, yes, I agree, it is complicated and that's because tables are complicated. In markdown you don't even have tables, so it's not really fair to say "look at the table syntax in asciidoc WTF, what a mess!".
[0] https://asciidoctor.org/docs/asciidoc-syntax-quick-reference...
[1] https://asciidoctor.org/docs/asciidoc-vs-markdown/#compariso...
|===
include::customers.csv[]
|===Markdown is the tool every one of us already know how to use.
> The markdown ecosystem is now riddled with non standard extensions and reminds me the browser ecosystem of y2k
Yet 99% of documentation I've written uses the basic syntax described here: https://daringfireball.net/projects/markdown/syntax
Extensions add to that basic set of tools, so even if you are using Github's flavor of markdown, every single developer on your tool is going to be able to read and edit most of your documentation without referring to any reference material.
Mind you, I started out in that frame of mind, since at the end of the 80's I used to write all my documents in a format that I no longer remember the name of. What I do remember is that it used dot codes, so something italicized would start with .i and .u for underlining. The purpose was to allow the dot matrix printers to over-strike, which provided much higher print resolution than the printer would normally be capable of. It had higher level codes for things like titles, etc, which is the connection I make to markdown.
Markdown languages allow you to get things looking reasonably good with extremely few attention-diverting things like format getting in the way of progress.
Except that the escape was replaced by a dot for the driver that converted it, and more "user friendly" formats like title (which was centered, bold and underlined). But I'm literally guessing since it was so long ago.
Efforts fail because:
- project leaders do not prioritize it
- project implementers are unwilling to write it
- documentation authors are unable to clearly communicate the important information
If the choice of markup becomes the limiting factor, existing documentation can always be transformed (either by machine or manual effort). But missing documentation always seems to come down to one of these three items.
How can that be? I mean, isn't that the simplest possible search? And as far as I understand it, Confluence search is powered by Lucene, a world-class library for natural text search.
How could Atlassian make it perform that bad?
Is there any explanation beyond "they are idiots", because they are probably not.
That said, it is clear Atlassian just sucks at search and doesn't really seem to care. Search in JIRA is even worse if you can imagine that. BitBucket is ok, but a different sort of use case.
I think they could make their search great if they wanted to, but why bother when the people purchasing the product probably won't even use the product enough to notice?
I found maintaining a good documentation inside a wiki tough. People (including me) will tend to create new pages willy nilly, never deleting old ones. The layout is generally rough, you generally have a basic structure, but under that, you see a mess of pages at every levels. The information is often out of date and often redudant which creates noise even if you have quality pages (and even if you have a good search).
The plus side of a wiki is its accessibility. Committing a text file inside a git repository is a tough ask to none technical people. Asking them to "fork" and do a pull request is even harder.
But to maintain quality documentation inside a wiki, a dedicated curator is almost always needed.
It's also not in or near the logical path of code/product changes. You need to login into a dedicated system, find the page you need to change or where to add a new page and finally do the edit. It's kind of hard to have a systematic good documentation in such circumstances. Also, doing reviews and documentation versioning (in sync with product versions) is kind of hard with a wiki.
For all these reasons, I tend to prefer putting my documentation right next to my code in a markup language (simple Markdown README.md for simple projects, RST+read the doc for more complex ones, but that's a personal preference). You have far more incentive to edit the documentation, versioning is automatic, documentation versions are in sync with your product versions, review is easier (just include it inside the PR, same as code review).
The downside is less outside accessibility. It's also a very "low altitude" documentation, great for documenting individual libraries or components, it's not so great for things like documenting overall system architecture, or organizational stuff like processes, basically anything not tied to one specific component.
In the end, wikis have their role, but I found they are generally overused and miss-managed.
We have a demo (https://nots.io/demo). Check it out, I'd love to get feedback.
I also have, multiple times in a 24-year career.
The XML-based monstrosities sold as “enterprise content management” have been bought by many a non-technical manager but never produced useful output once.
Nearly every parser implements one of the various flavors, which sometimes don't always work correctly.
Markdown is fine for first drafts, then to be pulled into ReStructureText or some other text-oriented but slightly more structured format. I'll give a shout out to Pandoc for making this easy (and for converting between Markdown flavors)
Google had done that, and in an exceptional whirlwind by self-motivated engineers who are delighted by having markdown docs in their repo, replaced majority of existing and legacy documentations with markdown files. This thing is called g3doc, and should be well known to people have connections with Google engineers.
Poor documentation of a project is not due markdown being used. Good documentation requires different types of docs targeting the different types of docs and different types of users.
When it comes to the ability to capture things in docs there's more that's useful than markdown can represent. For example, notes, warnings, etc. Tools like hugo have come up with work arounds that are outside of markdown.
Just saying... some things like asciidoc allow capture of richer information.
Still, the format isn't going to make the docs good or bad.
These days, I just use pandoc to translate markdown to PDF if I need to print and get almost LaTEX like typesetting.
"Both LFM and Markua are dialects of Markdown. Markua is newer and better than LFM, but there are still some advanced features in Markua that aren’t finished yet."
That's probably the largest criticism of Markdown - it was too incomplete, resulting in many different flavors, each of which may be incompatible with others.
That said - documentation in some consistent format is infinitely better than no documentation. Can always Pandoc https://pandoc.org/
However, from my experience of constantly dragging my colleagues to writing some small spec/docs, I would definitely fail if they had to learn anything at all in order to do so.
Show me a widely-available tool for rendering that please.
For everything else, there is basically no reason not to use it if you want to write documentation for people to read, rather than produce a typeset product for people to consume.
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...
I find that I can extend Pandoc’s markdown to do most of anything I’d want. Could RST or AsciiDoc do it better? Maybe. I haven’t tried. But markdown can do 80% of what I need right out of the box.
It doesn't do native nested tables, or that sort of thing, but for that I'd either drop to HTML or use Pandoc to embed something else inside Markdown. Tables are not fun to format in _any_ plain text language.
2. StackExchange Markdown is a prominent example of no-tables.
Any system that asks you to edit tables in a text editor is asking for trouble. That is a good time to look at a structured editor.