1. 27

  2. 27

    The absolute most important criteria (for me, anyway) is missing from this analysis. Which format leads to more documentation being written? For me personally, I loathe reST and I get its syntax wrong all the time. Comparatively, Markdown is intuitive, simple and easy for me to write. For me, it removes a barrier to writing documentation, which increases the probability of me writing documentation. It wins on that criteria alone.

    I know it’s not just me who thinks this way. rustdoc is purely Markdown. godoc doesn’t even support Markdown, and instead mostly renders only plain text with a few very small niceties. In other words, it gets out of your way.

    1. 5

      So this is just some insane rambling, I couldn’t sleep last night so please forgive me.

      In my experience “how much documentation is written” has a lot more to do with culture than format. This is why, for example, I really overall dislike wikis.

      One story I sometimes tell is that the only company I’ve ever really been happy about the documentation was when I wrote basically all of it. The situation was I was more-or-less the last technical person at the company and needed to help re-bootstrap a sysadm and support team and so needed materials for them for training and reference.

      The format didn’t matter much, since I was writing most of it I used emacs org-mode and exported to PDF. The PDFs were distributed out of sharepoint.

      What turned out to be a lot more important was the culture I established - that documents had owners and their email addresses were listed at the top of the doc. If anyone had questions or found an error, sending those issues to the doc owner was the right thing to do, and it was a significant part of my job to do the upkeep on the docs I owned. This worked really well in the short term, as really it was for my own benefit. As the last tech guy, I was oncall basically 24x7x365, which was totally untenable. The first docs I was writing were SOPs for common issues so we could offload some of the oncall responsibilities to the other teams, and just have them escalate to me when the SOPs didn’t cover the issues so I was pretty motivated to get all the feedback I could to make sure that those docs were as high-quality as possible, as when they had problems I didn’t get to sleep through the night.

      What surprised me was that in the longer term when I thought everyone else would start using wikis and such, that strategy was still really successful. At that point it was just the normal thing at that company and we’d trained everyone into it, so when they started writing documentation they’d follow my system (though generally authoring using something other than emacs…) The docs stayed really high quality, and surprisingly well up-to-date because we made sure that updating docs was understood to be a job responsibility along with everything else. Devs even included documentation time in their sprint planning estimates (which, you know, should be SOP but I’ve seen it disappointingly infrequently.)

      After meditating on this experience for a while I think the big problem with a lot of docs, regardless of format or distribution mechanism (word docs in sharepoint, wikis, three ring binders, etc) the hardest thing to avoid in documentation is diffusion of responsibility / the bystander principle (and wikis are especially vulnerable to this, since diffusion of responsibility is their raison d'être.)

      The big difference is the approach. Often what we want to see in wikis is: “this doc looks wrong, I’ll go figure out what the right thing is and update the wiki,” but the problem is that that operation is expensive. You need to research the issue before you update the doc. And that effort may be totally wasted - someone else might already know the answer. Since it’s expensive, often a lot less progress gets made. On the other hand, “this doc looks wrong, I’ll drop a note to jrdn since his name is on the top” is really, really cheap, and the work gets routed to the people most likely to already know the answer.

      The other big thing was keeping the docs in source control right next to the code, instead of separately (which is why I do quite like sphinx/markdown/plain text files again over wikis.) to continue to minimize the cost of documentation, but that’s a whole separate sleep-deprived insane rant.

      1. 2

        I don’t actually disagree with anything you said. :-) I can totally believe that culture plays a role in how likely good quality docs are going to be written. In fact, I believe there are many factors. But for me personally, annoyance threshold with the process of actually writing the docs is definitely on that list. Especially for projects I do in my spare time. (Which require significant documentation, just to name a few. For nfldb, just look at all the documentation on instance variables! It’s great! Sphinx supposedly has a way to do that too, but you either need to stick them in the doc string on the class or do some other hacks to get it working. Granted, this isn’t necessarily Sphinx’s fault, since the Python folks don’t seem to care much about documenting one’s data representation.)

        At work, we do actually keep a wiki, but we use Gollum which means that your wiki is just a bunch of Markdown files in git. It works great.

        At work, we do also use Sphinx for documenting our Python code. I loathe writing out the doc strings because I’m constantly looking up syntax for reST. I grant that at least part of it is because doc strings tend to contain explicit documentation of parameter lists (with types, of which the support is spotty), which can at least be partially avoided when writing docs in a language with a type system. (Many exceptions apply…)

        1. 1

          annoyance threshold with the process of actually writing the docs is definitely on that list

          Oh yeah, formats definitely factor into that cost-of-documentation, personally I’ve just found it to be a relatively minor factor compared to the other ones at most of the organizations I’ve worked in. Getting a good format that works well definitely helps, and there is a big benefit to simplicity (read as: I can’t remember how to write reST either. Thank goodness Emacs generates most of the basic sphinx stuff for me and I only need to look it up when I need something a little weird.)

          I understand the author’s frustration with markdown, as I’ve definitely encountered some lack-of-standardization problems with it, but unfortunately that’s probably just the nature of the beast. Part of the problem is the inexact standard, but another part is that there are a whole bunch of implementations. There are a bunch of reST implementations as well, and not all of them support all the same things, so you have the same sort of issues anyway. I think the main reason I’ve had the problem less with reST is more just that there are fewer documents I have reason to use with multiple implementations, more than the standard keeping everything compatible.

          Yet another reason to like org-mode, which (basically) only has one implementation. No compatibility… no compatibility problems!


          I don’t actually disagree with anything you said. :-)

          And just wanted to say I definitely didn’t intend for my reply to come of as a rebuttal to your comment, so apologies if it did. It was more just that your comment inspired me to indulge myself in a rant, all my coworkers have heard that one a couple times now so I thought I’d just drag it over here to introduce it to a whole new audience :P

          1. 1

            Yeah, I guess when I wrote my comment I was thinking a lot more about what I’m doing in my free time versus work. The annoyance tolerance is definitely quite a bit lower for stuff done in my free time.

            I think the only thing I’ve been bitten on with Markdown is the fact that reddit doesn’t support the triple backtick syntax for code blocks. Other than that, it’s been pretty much smooth sailing.

            Yet another reason to like org-mode, which (basically) only has one implementation. No compatibility… no compatibility problems!

            I took up arms with Vim long ago, but it does appear to have a orgmode plugin.

            1. 1

              Yeah, there are even some efforts to bring it to phones in Orgzly and MobileOrg.

              I have hopes for some of the new implementations maybe bringing org a bit more into the mainstream, but it’s going to be an uphill battle for them. The basic features in org are pretty doable, but then there’s all sorts of other cruft that’ll be a bit more annoying to maintain like the calc based spreadsheet and the literate programming stuff.

              Then again, it’s probably safe to ignore most of that in most contexts, maybe it would be a good idea to try and define some standardized subset of org to target for compatibility across implementations.

      2. 4

        Which format leads to more documentation being written?

        Absolutely agreed. I understand that Markdown is a terrible language. So is English–it’s got a textbook defective orthography with pathological phoneme/grapheme correspondence. But that doesn’t mean I’m going to start documenting my projects in Esperanto or Quenya.

        1. 3

          This is an uncharitable interpretation of my comment. I personally am more likely to write more docs using markdown than reST, and i attribute that to finding markdown easier to write.

        2. 2

          For me personally, I loathe reST and I get its syntax wrong all the time.

          This is probably more related to previous experience with other markups than a specific sphinx property.

          1. 4

            … or it’s related to the fact that some markup languages are more complex than others?

            I’ve tried using Sphinx, which is an altogether separate issue that the OP. (In fact, I do, at work.) It’s so much more complex than what I think is necessary that I wrote a replacement to epydoc for my auto documentation needs. Example.

            1. 1

              Not my experience. I started trying to learn reST when my only previous markup experience was MediaWiki (which is unlike any of these others). I gave it a good go, couldn’t make it work for me, gave up and started using Markdown and it was so much nicer to use. UX matters.

          2. 18

            Lack of extensibility is great. Semantic markup is very rarely the right tool for the job. I want to like reStructuredText but it’s nowhere near as nice to write; ditto asciidoc.

            Markdown is definitely one of those “not when there is nothing more to add, but when there is nothing more to take away” things. I would generally try to avoid flavours; I definitely wouldn’t switch to an extensible format over markdown.

            1. 3

              I recommend checking out Asciidoctor if you find the original implementation a bit obtuse. Asciidoc implemented a bunch of nicer styles, and they are the default in asciidoctor documentation.

              1. 1

                I’ve found that suggestion hard to follow in practice, because I almost always need at least one thing not in “basic” Markdown. A common one is footnotes. (Although this is for essays, not documentation.)

              2. 2

                We use asciidoc at Elastic and have been (mostly) happy with it. We use a single book-per-project, but the entire documentation is built as a single book to allow inter-project linking. What’s nice is that the docs will fail to build if inter-project links break (e.g. another team re-arranges their documentation or accidentally change an anchor). Basically eliminates link-rot.

                Asciidoc itself is fairly powerful, and you can express most practical layouts that you may want. Tables can be fairly janky, so I personally try to stay away from that. Honestly, my major complaint is that the build errors are often very cryptic. For example, if you use the wrong heading “size”, the build may not break until later in the book when it encounters the next header and barfs. Which can be tricky to diagnose back to the root problem.

                All in all, git + asciidoc has been a good experience for us in terms of maintainability, versioning and flexibility.

                1. 2

                  Orgmode baby. You can export to many formats.

                  1. 2

                    org-mode is just totally glorious, unless you happen to work with people who don’t/won’t use emacs. It’s my tool of choice for authoring stuff when I don’t need to collaborate, though.

                    That said, I did once work with a crazy guy whose love for org-mode was only equaled by his love for vim, so he just wrote org docs in vim… Most of his editing would be done that way and then he’d boot up emacs whenever he needed to do exports or recalculating tables or something. It was weird.

                    1. 1

                      I draft in org mode anyway, then export to whatever format I need for collaboration once I’m near done. Gists render org very nicely :-)

                      Sounds like your crazy colleague needed to discover evil mode :-)

                      1. 2

                        Actually I showed him evil, but he didn’t like how emacs took longer to start than vim. Then I showed him how to run emacs as a daemon and connect with emacsclient. Then, finally, he admitted it was just an irrational preference thing, and I went back to my office to let him vim away in peace.

                        1. 1

                          Some people can’t be helped.

                  2. 2

                    I agree with this. Sphinx / reStructuredText is much nicer than Markdown for anything requiring internal links, or spanning several files. Sphinx is much less pleasant to actually write though, IMO. Writing code examples in either is frustrating, because of the extra indentation required.

                    Since I discovered Org mode I’ve started using it for more and more, and now draft most things in Orgmode. If the destination doesn’t support Org—which GitHub does—I export to either Markdown (for StackOverflow/Lobsters/others), JIRA, plain text (for emails) or reStructuredText (for our Sphinx site). Mainly it boils down to convenience. Org syntax is a little more explicit and verbose, particularly than Markdown, but the Editor support is superb and the shortcuts and templates means it is actually less effort to type. If your documentation contains tables you can’t get much better than the org table editor. Also, org-babel is absolutely outstanding. Org mode also lets you edit code examples in their native modes, which eliminates the extra indentation problem.

                    1. 2

                      Why is orgmode never mentioned in these discussions?

                      1. 5

                        I would guess because it requires that everyone be using Emacs (at least, that’s my impression; I would love to be mistaken). I really enjoyed Org for personal projects when I was an Emacs user, but for documents that I wanted everyone to be able to read-and-write I would be leery.

                        1. 2

                          I would guess because it requires that everyone be using Emacs (at least, that’s my impression)…

                          It doesn’t. There are Vim and Sublime Text plugins to take advantage of org-mode.

                          …but for documents that I wanted everyone to be able to read-and-write I would be leery.

                          A big point on org-mode is that you’re still dealing with plain text, just that there are special interactive additions when used in a compatible platform. Then again, your mileage may vary since I just got started learning how to use it. It probably isn’t mentioned that much since it seems to make for better note-taking and outlines than normal documents.

                          1. 3

                            The Vim plugin – last I knew – did not handle most of org’s extended functionality (e.g. code evaluation). Ditto for ST. The Vim plugin also depends on Emacs to do exports, which just adds another dependency that can cause breakage (actual real-life example: one system had emacs updated, which included a new version of org-mode. The other didn’t. Export results were different). Org is still very Emacs-centric to the point that you’re basically SOL for any but the most basic features outside of Emacs.

                      2. 1

                        You should use Markdown for what was created: Simple snippets of text (blog posts, comments, READMEs) with some basic markup and structure that can be read with a basic text editor.

                        If you have to write “serious” documentation, use TeX/LaTeX or something thought for the task.

                        1. 1

                          Markdown is fine for situations where plaintext would also fit.

                          Markdown isn’t very fine for situations where you actually need features that would be part of flavors.

                          1. 1

                            If you’re just using it for what’d a README.(txt|html) would be, it’s fine. Most have standardized on GitHub extensions and behaviour, for the most part.

                            Now, for semantics and structure? I agree.

                            1. 1

                              I’ve recently ran into an issue with using markdown to draft papers for my dissertation. Per APA Ver 6, double spaces are expected after punctuation to “improve readability.” However, I’m using pandoc to convert my drafts to docx, the standard that my school expects. I spent way too much time learning just enough haskell to determine that pandoc doesn’t detect the use of double spaces and cannot easily be modified to both detect and write out double spaces without breaking most of the tests. I eventually had to modify another tool (https://github.com/jamessantiago/DocxMerge) in my workflow to add the the spaces back.

                              But what’s the alternative? Commonmark and Asciidoc don’t get my use case to a working state. Toolchains for specific use cases will always be a thing and I expect this to be the case for many developers with strict documentation requirements. There’s always that one customer (or school) who just has to have documents in word with double spacing after punctuation.

                              1. 1

                                I just started using doxygen at work and i like the way it is lodged in the code. If you add a function, add a comment, simple. The only thing i wish it did is update/generate comments as you compile. I know it can’t work out the intent of each class/function/parameter/variable, but at least adding a template doxygen comment that mentions the function, parameters and return would be good maybe with a “TODO: Fill out doxygen comments”.