One point that's not really touched upon is the fact that it really does matter whether the person writing the documentation is a technical writer or a developer.
If you're a tech writer, you're probably interested in using the best tool for the job, because writing documentation is what you do day in, day out. If ReStructuredText is the most powerful format, then you're going to strongly lean toward that.
If you're a developer, however, writing documentation -- while you may recognize its necessity -- is a task that is often a slog. It's something you do so you can get it out of the way, and you really don't want to spend very much time thinking about the "how." You especially don't want to spend very much time learning the intricacies of a new markup format, unless you absolutely have to.
I say this as a developer who is also a writer. I enjoy writing, but I know many developers don't. And if Markdown makes it easier for them to write documentation, either because they're already familiar with it or because it's just a simpler format, then I'm all for it, even if ReStructuredText might be a bit powerful overall.
Completely true, until you need a feature that the less powerful format does not support. Then you are back at the beginning, regretting spending all that time learning something that won't fill your needs.
ReStructuredText is not hard. Yes, unusual features are hard to memorize, but a quick google search beats it being impossible every time.
Though this could be said for literally anything you learn how to do. I spend my time learning the tools that will give me the biggest impact most of the time, and use the easiest tools for most other things, simply dealing with their deficiencies.
I wouldn't say Markdown is simpler. It has fewer features, but the core experience is about the same as reStructuredText.
RST header markup is more readable in plain text. In Markdown, the less important a header is, the more hash marks. In RST, I am free to make less important headers have less visual weight.
Markdown also supports non-hash mark headers, similar to RST, but it is a bit tougher to deal with its h1 -> h6 progression than RST. The RST rules are clearer and standardized, whereas Markdown's are not and especially vary between engine implementations. One more area where CommonMark standardization may help some time in the future, but doesn't quite impact today.
They're standardised but I wouldn't say they're clearer as the "level" of a specific over/under symbol only depends where it first appeared in the document, I've seen projects where two documents side by side used different underline symbols for the same depths, that gets confusing.
I'd like rST/Sphinx to be stricter on this point, maybe I should open an issue/PR allowing upfront definition of the over/underline hierarchy for the project.
Agreed, RST headers are too "flexible". They're also IMO quite annoying to write and maintain (exactly matching the title length) or ugly (overlength).
Plus, solving inconsistencies with simple head math: $ to the end of lines to get the character counts from the two line and say, add 3 with 3i=[Esc] or subtract 5 with 5x. With over and under decoration you can . the other side to fixup both.
Header significance to visual weight inversion is the same deal in the lauded orgmode. In both cases, the trick is to see the hash mark weight as indentation instead of significance, or, preferably, configure your editor to weight the headers using font customization.
When working in an entity, use whatever the team is using obviously.
Otherwise, if you haven't learned any of those two and are wondering which one you should pick, it's cool, because
> You especially don't want to spend very much time learning the intricacies of a new markup format, unless you absolutely have to.
is moot anyway. Starting to write in RST is not more complicated than starting with MD. No need to learn the minute details to write basic documents. You will have plenty of time afterward to refine the thing once you're accustomed to it and feel the need to produce more advanced outputs.
As a developer, I would LOVE a tech writer to sit next to me and walk me through the best way to write documentation, using the best tools. And by "best," I don't mean what I think is best, I mean what the professional tech writer thinks is best. Until I have the experience to opine to the contrary, it is my responsibility as a software engineer with a mission to produce quality software to care deeply about documentation, even if it's not my full time responsibility. I would love to see more articles about the "how." I would learn a lot and be a better software engineer as a result.
Thanks for that, although I don't think those particular tools apply in a polyglot sense, the concepts establish a nice pattern to replicate in other tool chains.
I actually recently introduced RST and Sphinx to our documentation team of 4 non-developers, and the most difficult hurdle was actually teaching them to use git (even with GUI SourceTree). Getting multiple non-developers (2 are remote) how to install Xcode and Docker produced more confusion then I thought it would. We've finally gotten into a flow, and better documented how to install the documentation tools, and it's been working quite well.
You mean like vim, emacs, nano, kate, notepad, notepad++, wordpad, or any other plain text editor?
Really - I don't get this impulse at all. From my perspective, the entire point of markdown (and RST I assume, though I haven't used it) is that you can easily read and write it using any plain text editor.
If you are going to need a specialized editor to write it, you might as well use html, docbook, docx, odt, troff, rtf, or any of the zillion other formats.
Back to the main point, for non-developers all of those can be quite confusing especially when you're used to Word/Google docs/etc. A text-only editor where you don't get live feedback is quite an adjustment and there is a cognitive switch to the text you're writing and imagining how that text will be presented.
It's been a while since I've written rST but there were good plugins for both emacs and Sublime to boot (for e.g. filling the header under/over line or toggling between different header styles)
I don't know why this is such a common opinion. I'm reluctant to write docs exactly for the reason of not knowing the best tool for the job (or even an "ok-tool"), and I don't really have a luxury of finding it out exactly because I'm a developer and have stuff to do aside from writing docs. If I already had developed a workflow for writing docs, I assure you, writing a manual would be no different to me from writing a parser or some RPC-server or whatever. The only difference is I already have a workflow suitable to write parser, because I've written tens of them, maybe over a hundred already. I'm only thinking about the business-logic, my fingers just do the job.
On the contrary, when I'm trying to write a manual larger than a few screens, say, docs for an API with more than 20 entries, I have to think about the tools to write, compile and display the documentation in a way to be comfortable for both the developer and the user. I'm not in a mood to write my own, and the Internet recommends me to use something that requires installing whole Ruby dev-stack (and I don't use Ruby) and produces something hardly even readable. That's why using markdown + pandoc, or even google docs might be something I resort to.
If somebody would show me "The Way", spending a day or even a week to get fluent with the tooling I can use from now on would seem to me a minor nuisance, hardly even noticeable.
No way. First, it has to be hosted in house. Second, that's basically the same markdown + pandoc I use for free already. Except it's even less flexible, and costs money. If API documentation would be just an ordinary book, I wouldn't have the urge to change anything, as pandoc + custom CSS actually does fine. Generating HTML + TOC from a bunch of .md files isn't really a problem, you know, it just isn't what makes writing API docs painful. I have a couple of sentences to say about every RPC call, maybe. It's actually mostly about providing huge (so, I guess foldable) params/result examples and making it easier to change the docs when the code changes. See Slate for example. Or even readthedocs. Both are not even remotely perfect, but are wa-ay more suitable for writing docs than gitbook.
A couple years ago I put together one of the more popular themes for Sphinx. It's the one used by Read The Docs and you've likely seen in countless times when searching for Python libraries.
I prefer Markdown.
It's readable and easy to start writing by non-technical folk. More than that that, it's less flexible and isn't as likely to be destructive. At the end of the day rST is as complicated and as flexible as something like HTML. The biggest problem is its ability to nest markup. Markdown is pretty flat and you're not putting lists within tables within blockquotes. As someone making a theme, it was pretty difficult to style against the level of nesting that people end up using rST for. This is of course me bitching about how people write their rST, but there it is. I think rST by nature leads to inconsistent markup.
Basically what I'm saying is. At that point, I'd rather just write HTML. rST sits in some weird middle world where it can get very verbose, but you end up losing all the simplicity that you wanted in the first place.
Also want to note that rST doesn't HAVE to be so complicated. Plenty of people write clean, rST docs. However, as someone who spent a good deal of time learning the Sphinx system and the markup quirks of rST, in general I ended up seeing people use it in all sorts of crazy ways which then led to weird styling errors.
When it came time to document my own projects, I just built a simple markdown system with a tree structure and added some syntax highlighting. That's gonna get most projects 95% of the way there. While you can do a lot more with rST and it is really powerful, I really think it's only for those 5% of projects or more than likely, scientific documentation that needs more context.
I don't think there is anything in RST that encourages deep nesting level or verbose markup, on the contrary with default roles it can be more compact than Markdown. If you look at good documentation examples, like The Python Standard Library documentation (https://docs.python.org/3/library/index.html), nesting is very limited and the documentation source is very clean and readable.
I agree with everything you say. All I'm saying is that in practice, the rST docs I saw, and the issues that came up around theming rST docs led me to believe that the flexibility of rST was its biggest problem (and strength).
Markdown doesn't have that problem because you can't do much with Markdown.
Ultimately, I lean towards rST since you can combat complexity with "good practices" (as a Python guy this is akin to being Pythonic) but the opposite is not true for less complex implementations.
After having written a fairly popular 400+ page book, and dozens of documentation sets in Markdown (and having worked on a few in other languages), I have to say—Markdown is _good enough_.
It will take an order-of-magnitude difference to unseat Markdown as the 'simple plain text formatting syntax' default, IMO. But use what makes you productive and is most conducive to writing effortlessly!
I wrote my dissertation in markdown because LaTeX added so much noise to the text. In the end I had to go back and manually reformat chunks of it in LaTeX (especially the floats), but it was still worth it for all the bits I never had to write LaTeX for. In the end, it's not either-or, it's Markdown plus conversion to something with more knobs to turn. (All thanks to Pandoc!)
Pandoc even lets you include LaTeX in your markdown, so you can just use it inline for the few times you need more control, without having to faff around editing the output.
Yes. Depending on what are you including, a better alternative might be to use Pandoc filters that change their output depending on the output format. So for latex you might end up with fancy figures side-by-side, but for word you just have them as figures one after an other
I must add Asciidoctor. Which is mostly compatible with Asciidoc, but even more powerful.
I have spent a lot of time trying to make Asciidoc create beautiful PDFs for technical documentation, but Asciidoctor makes it all a lot easier to customize its own stylesheets.
The only negative thing about it is that it is hard to install since it typically isn't found in your distros package repo by default.
Thanks to your comment I just tried out Asciidoctor and 'it's absolutely beautiful. It's insanely easy to install on OSX/Linux systems. I can see myself using on some of my pet projects.
I agree. For me, Asciidoc hits the sweet spot as it seems to have much of the simplicity of Markdown, and with the AsciiDoctor/DocBook toolchain it has the publishing power of RestructuredText.
But its tables beat both hands down. You can include a csv file with some headers or micromanage merged cells, alignment and such.
I was in attendance for a conference presentation a few years back that O'Rielly was moving to writing books in an asciidoc editor which would be converted to (x)html5 for easy conversion to PDF and ePUB.
I wonder if that thing ever took off. Previously, it was said, that they were working in docbook (XML)
AFAIK (I have a few friends who have written for O'reilly) this is their canonical mode of publishing. It uses Git and Asciidoctor (not asciidoc) with a few additional plugins
I would also add that Asciidoctor has the best extension experience out there. It has named blocks and inline sequences that can be handled correctly by a plugin, which is amazing if you ever tried to add syntax into Markdown. Just compare how bug-free and simple is embedding Mathjax into Asciidoctor compared to Markdown: last time I've checked you had to manually process Markdown to extract all Mathjax stuff, apply Markdown and then inject Mathjax back. With Asciidoctor it's a no-brainer.
I looked into these recently and found AsciiDoc the most promising for lightweight technical documentation, but I'm still having a very hard time getting myself to use it instead of Markdown.
AsciiDoc has some very newbie-hostile quirks, at least as of now it more or less requires asciidoctor, and even then its output HTML is terrible. Terrible as in Wrong, as in...
<div class="paragraph"><p>Oh no...</p></div>
In fact, since I have not yet found an asciidoc converter that produces decent HTML, and I don't have time to write one, I may yet fall back into the "everything sorta supports Markdown" trap.
Markdown is one of those "worse is better" computer pop culture things that raise to the top, despite the existence of better tools.
I dare anyone to write a scientific paper or book using Markdown. In Asciidoc it's doable. And before you say that a markup language is the wrong tool for the job, let me remind you that nowadays authors might want to produce different formats (HTML, ePub, text-only) from the same source file which is difficult with LaTeX.
If you consider Markdown on its own, I agree that it's rather difficult, but you should really try Pandoc, any output is possible, including scientific papers (pandoc-citeproc is fantastic) and books. Without Pandoc, Markdown would be very limited for my use cases.
I had forgotten about PanDoc! That's true, for some time I was pondering going Asciidoc vs Markdown+Pandoc. I liked the "purity" of Asciidoc (most things you will ever want to do are built-in), and Pandoc felt like it was a non-portable collection of hacks to get Markdown to do useful things.
I wish I had time to evaluate them in more detail, but so far I've stayed with LaTeX, which I feel is not the right tool for the job for material that's not going to be printed on paper.
I think it's more the case that there is no good general-purpose solution yet, and a bunch of people use Markdown because it's easy within a very limited scope, so now you have to deal with Markdown's near-ubiquity if you suggest something else.
I would never try to write a book in Markdown, no matter how extended; but considering the HTML produced by asciidoc|tor, you might also say "don't use AsciiDoc for simple Web publishing."
What I find much more fascinating is the question why there is no good general-purpose format that works equally well for blogging and for scientific papers and for books?
Indeed. We recently started a large rewrite of our product's Developer's Guide which was previously written in DocBook. All the writers are quite happy about Asciidoc and it took us only a few days of work to recreate custom additions we added to DocBook.
That being said, while the user documentation is (mostly) excellent, the developer documentation is abysmal to non-existent. On the positive side, though, the developers are quite active and responsive on Github. But if you're only writing documents instead of extending the language with new macros, you won't notice anything of that.
Asciidoc is really underrated. It feels more "natural" than RST and scales up to large documents.
I wish people spent more time looking at alternatives instead of jumping on bandwagons.
This whole argument presupposes that anyone who cares will get a choice in the matter. We all know that most bespoke software is written for corporations. And despite the immense drawbacks of "Word" (too many to mention, but let's start with autocapitalization...), most bespoke software is documented in "Word" despite "Word" not being fit for that use.
To me, this is like watching intense baseball fans argue who was better, Babe Ruth or Joe Dimaggio - neither one of them is going to play again.
So here's a story: I work at a large engineering company building custom automated research systems. The system engineers do the the design/development/testing and documentation.
I have been searching for nearly 9 months for a documentation system to replace our current documentation system (500 Word docs in an EDMS). Goal is to increase re-usability and decrease maintenance cost by something more like a wiki/markdown system.
The problem is, even though formatting and maintenance of Word docs is abysmal, they make inserting images and references drop dead simple. Plus, everyone has it installed on their machine.
All the markdown versions don't have good references or image support (plus the best IDE is gitbooks which is... buggy). RsT is too much of a burden to setup. These are engineers writing, not programmers.
I've looked into Confluence, Gitbooks, Dozuki, Inkling, Sphinx, ... nothing is quite so friction-less to "just write the docs" than Word.
It's not even so much the friction-less nature of "Word", it's just that's what testers, PMs, Managers, Directors, Executive Directors, Vice Presidents, Executive Vice Presidents, etc etc all have and understand. Very few people even seem to find "Word's" grotesque shortfalls as engineering documentation to be a problem. Beyond not being able to ever completely turn off auto-capitalization ("boolean" and "Boolean" aren't the same in Java, people!), the lack of a line-by-line diff makes getting feedback on a document painful and impossible to get correct. Nobody in their right mind would accept binary blobs of code as a "new revision" - you couldn't see what changed, for starters. So why do we just accept WITHOUT THOUGHT binary blobs of documentation? Try to make that argument to a PM, and they'll look at you like you're growing a second face on your ass.
I agree -- I originally wanted a markup language to do away with LaTeX for typesseting but then I realized that getting image sizing and placement right on any markup language is even more painful than with LaTeX, so I just never jumped ship.
I still wish I had a publishing toolchain that produced multi-format output (HTML5, docx, ePub, Kindle, and plain text) from the same source file. It can be done with LaTeX sources but the result is sub-optimal.
As I wrote in another comment, this can be done quite easily with Pandoc. It is a really powerful processing tool and with the right set of templates it can do wonders. Have a look at Kieran Healy's work: https://kieranhealy.org/blog/archives/2014/01/23/plain-text/
For some definitions of "easily". For a programmer, yes.
For an enterprise organization with a full gamut of technical ranges from "maintain 40 github repos for fun" to "I still don't trust anything but Word, Excel, Powerpoint and email", pandoc is not the solution (as nice a tool as it is).
I found references in markdown incredibly simple. Using BibTex or CSL styled JSON objects. Then just chose the CSL style your institution prefers and run it through pandoc. Gives me html, latex, pdf, ePub, and even docbook or TEI for those with an XML fetish.
....but image support. Ugh don't get me started. Thankfully we use it right now for simple articles so the figure doesn't need to do much.
Yeah. I've played around with everything mentioned in this thread, and for documentation that needs refs/math/images, you need to use either Lyx or Word. Asciidoctor might get there if it ever gets a good, free development environment.
Very true, indeed. I gave up on latex and simplified markups and I even abandoned my own converter for this very reason. Today, I use Word because that's what people higher up expect to get.
1. Do you want to write something that MD is sufficient for? Write MD.
2. Do you want to write something that you need RST for?
2a. Is your document already in RST or is there no document? Write RST.
2b. Is your document in MD? Pandoc to RST. Pretty print. Write RST.
The reason this is useful is that the 90% use-case is probably hit by MD. You may never need RST. And you won't spend more time deciding and discussing than actually doing because this algorithm only takes a few seconds to execute.
RST has some great ideas (as mentioned in the article, roles and directives are fantastic ideas). But it also has quite a lot of unnecessary complexity built in. It's also great that it (kind of) has a specification, not just a bunch of hand waving. But even with the specification there seems to be no independent re-implementation, so I wonder if the specification is really complete. It also makes some syntax choices that just make no sense at all to me. Making the most basic and important feature (bullet lists, titles) annoying to use was not a smart move.
The (only) good thing about Markdown is it's (allegedly) simple. IMO it's on the one hand not simple enough (e.g. HTML has got to go) and on the other hand it's too simplistic.
Ideally I would like to have a tiny core specification with a clean and simple standardized mechanism for extensions like roles and directives. With a bunch of standardized but optional extensions. Only the most important features (90% of usage) should get special syntax (bold, bullet lists, titles, roles, directives). For everything else (90% of features) there should be a named role or directive.
Trac actually uses a similar system. linkExtensionName:content, [[extensionName(content)]] or {{{#!extensionName multiline-content }}} is all you need to remember. Could be simplified a bit, but it's quite usable.
This has also been my experience of RST: it adds a huge headache of complexity. I've also found its documentation and tooling to be very poor. Tastes may vary, but my experience was that almost every feature ended up with an obtuse name that needed a tremendous amount of searching for, the docs had inexplicable & glaring lacunae, and that the error messages that the tools omitted were infuriatingly unhelpful. Writing RST was an exercise in pain for my team. For the problem domain it was built for, Markdown works, works well, and works with few enough moving parts that you can actually figure out where your errors are, should you drop any in. This is very much not true of RST: the tools hate you with a seething, brooding hatred that will make you waste an hour trying to track down the one line in file X that's making the compiler emit a cryptic error about file Y. RST has some good ideas, but as far as I can tell, no-one involved with it takes usability seriously at all, which in turn means that they produce software artifacts that express a shrieking, gleefully sadistic hatred for the user.
I've used a lot of RST and from my experience the specification is very accurate. If there is some inconsistency, it should probably be considered as a bug and reported to Python docutils. What exactly is the problem with bullet lists? AFAICS they are pretty much the same in Markdown and RST.
b. In RST you must indent child bullets exactly to the indentation level where the text starts in the parent bullet.
Also untrue as far as I can see. Vim does do automatic indents for me so they have to be consistent AFAIK, but not to the `exact` same level as where the text starts in the parent bullet.
However, commonmark currently lack support for tables, so I fall back on rst for tables(actually I think the syntax for tables in rst is much better than tables in other markdown flavors).
Also, resolving links using commonmark in sphinx is a mess, right now. I actually extended recommonmark so sphinx will properly resolve cross references(including reference to elements in a domain). However, I had to update sphinx as well, which I have a PR open with no response from them, here:
It seems unfortunate that sphinx devs are unresponsive to contributions. The devs for mkdocs are a lot more responsive, but seem more interested in monetary contributions, unfortunately.
I'm still using Textile. My blog engine (https://github.com/rcarmo/sushy) can cope with ReST, Markdown, Textile, raw HTML and iPython notebooks, and I still turn to Textile for complex tables and other niceties. Out of the 7000-odd pages on my site, most complex pieces are Textile (although most newer items are Markdown).
I find ReST incredibly awkward to use, really, because it's anything but intuitive - both Textile and Markdown are easier to write off the cuff.
More importantly, though, I really wish that Textile, Markdown, ReST, etc., were formally specified as PEG grammars or similar. There's just too much variation, and "standards" or specs defining them tend to be written in ambiguous English rather than something that could be formally validated and easily ported across to new languages (rather than the spaghetti messes of regexps that most parsers turn out to be when you look at the source).
While I do like simple markup, I think that all markup languages will become a lot better when text input hardware slightly evolves. We are so close to having this.
We have Unicode but most of its symbols are a pain to generate on conventional keyboards.
We have touch-screens but desktop computer keyboards don’t offer them and software on phones/pads still tries a bit too hard to emulate a conventional keyboard layout.
Imagine if all standard keyboards had touch displays on the side to quickly flip between tables of related symbols, optionally with some context-sensitive mode? Then, instead of having to use creative ASCII tricks to make it “simple” to describe what you want, you just do it through your input device.
Ultimately I think markup languages will have to distill their features down to a few structural elements, and rely on Unicode (and easier Unicode input methods) to handle what is currently being done with ASCII hacks.
A keyboard with OLED keycaps that change depending on the context would be reason enough to get a new laptop altogether, even though I have a brand new one.
As someone who context-switches from XCode to IntelliJ to Photoshop to Emacs, sometimes I confuse the shortcuts, and I don't learn more shortcuts because I'm afraid they will not carry over to other programs. Having discoverable shortcuts would be amazing.
Nope, but it doesn't surprise me. I found bitbucket's markdown so limiting that I gave up on it. I suspect they'd rather have their users on Confluence instead.
The markup Atlassian uses in Jira isn't Markdown at all. It has a few general similarities, like the use of asterisks for bold, but otherwise it's so different as to essentially be its own thing. (For instance, it uses [text|http://example.com/] for links, which isn't even remotely like Markdown.)
But if one of your main selling points is integration, you'd better standardize to one, especially if (as an other commenter pointed out) the one in bitbucket is subpar.
No argument there - but no surprise either that upgrading bitbucket's markup might be something lower down on the priority list for the Atlassian engineering team either. :)
Having authored texts in nroff, groff, HTML, DocBook, Markdown, ASCIIDoc, and LaTeX, as well as numerous proprietary formats and word processors, my considered view is this:
Let authors use the fucking tools they know and prefer.
Organise common text through translation tools. Pandoc is fucking amazing.
Formatting for final production is a separate task.
(Not without some irony, I'm reviewing a set of guides and commentaries on productivity and creativity in a few other tabs....).
When you are writing your most important task is to capture the gist of what's in your head onto a tangible medium. If that means fucking Messinian marble and diamond chisels, so be it.
The marginal productivity gains for someone already proficient in a tool are low in switching to something else, relative to domain knowledge.
The challenge is that you're then stuck with high-level, vs. low-level definitions and tools. Which is where the whole "what do I use for creating my documents" question ends up at.
Systems such as HTML5 (the semantic elements, not all the canvas and DRM crap), or LaTeX, or DocBook, are hugely useful here because their definitions are largely semantic. You write the structure, not the style.
After that, so long as a tool or language can produce ingestible input given an author's output, that's fine.
And, frankly, by the time you're worried about specific low-level structure, use a dedicated tool which provides that. My experience with LaTeX was that it was actually _amazingly_ simple to use for basic creation -- it gets out of the way. Paragraphs as linefeeds, rather than HTML's incessent <p> </p> pairs, helps immensely. For more complex structures, you can go back and add what's needed later.
Markdown offers a wide set of capabilities with the option of fallback to HTML, which again is powerful and a good option for composing.
I'm in the middle of converting a project's legacy plaintext documentation (emulating man page format) into RST/Sphinx. The support for semantic markup with roles and directives was attractive for my goals (without falling down the rabbit hole, being able to: 1. translate from one source to formats compatible with both presentation-markup and semantic-markup, and 2. lint the docs).
I've come to rue this decision in some ways. I like what I've been able to accomplish, but I've found most customization of default Sphinx and docutils behavior to be torture. I don't mean to drag contributors to those projects through the mud--they work well if you can just write documentation without fiddling much.
It's a Python package that allows you to extend markdown through pandoc filters. It allows you to easily manipulate the AST created by Pandoc to add any number of features.
For instance, I wrote my dissertation in Markdown , and used this to include algorithms, CSV tables, include directives, etc.
Another interesting publishing system is Pollen http://docs.racket-lang.org/pollen/. It integrates with Racket to give you the full power of a programming language while writing markup. The guy behind it, Matthew Butterick, is a typographer and has put a lot of work into it.
When I started writing the documentation for a software product I make I went with Markdown. It was what I knew and I thought it was great.
As I started writing the documentation though, Markdown's drawbacks became more apparent. Especially as the software I'm making is multi-platform and there are features that exist in one platform and not the other and I'd like to include/exclude documentation of those features based on platform, and the fact that I'd like the documentation for each platform to contain images from the program running on that platform, and so on, and this is not something that Markdown handles well.
And so I switched to ReStructuredText. RST is not as clean or as simple to write compared to Markdown, however if you are producing documentation then it is much more flexible. I can live with less clean syntax in order to get the flexibility to do what I need to do.
What blows my mind is that every time I need to write anything in markdown (once a month or so), I can never ever figure out how to use it without doing tons of googling. Why can't sites add some easily accessible documentation?
Hacker news, tumblr, reddit, github all do it. Honestly, if it didn't look fine in the editor and then throw an apeshit fit when posted, it wouldn't be that frustrating. But I'm so damn tired of hitting "preview" or editing my posts after posting because of misleading previews and text boxes.
There's composing in a lightweight markup language, then moving to something heavier-duty. HTML, LaTeX, DocBook, whatevs.
The lightweight language is an authoring tool, but it shouldn't get in the way of full expression as needs be.
(Markdown allows integrated HTML, though not all Markdown implementations / uses provide that, particularly online Web tools. Which are horribly inconsistent, IME.)
Leanpub promotes a superset of Markdown called Markua. It is claimed that Markua is more suited to the writing of books and documentation. See http://markua.com/ Personally, for my projects, I use rST, but that is only because the wind happened to be blowing that way the day I made my choice.
I really wish Adobe didn't screwup FrameMaker. It was on all the major platforms and did its job. Then, they went and dropped it from everything except Windows and it's basically languishing ever since.
I wrote a number of documents in FrameMaker back in the 90s and I loved it. I really wish I had something like it now.
> In the real world, people use Microsoft Word, or even LibreOffice Write.
Please point to towards an API or library documentation written in the native format of either of those. In 10 years as a developer, I've never come across such a thing.
> Yet another flavor of Markdown is not helping.
Agreed. That's pretty much what the article states, and RST, luckily, is not that.
The C# and PowerShell specifications are written in Word ;)
In any case, there's a lot of things people use in-house and never bother to tell the outside world about, and you'd be surprised how far that is from what people on HN or Github habitually use.
If you're a tech writer, you're probably interested in using the best tool for the job, because writing documentation is what you do day in, day out. If ReStructuredText is the most powerful format, then you're going to strongly lean toward that.
If you're a developer, however, writing documentation -- while you may recognize its necessity -- is a task that is often a slog. It's something you do so you can get it out of the way, and you really don't want to spend very much time thinking about the "how." You especially don't want to spend very much time learning the intricacies of a new markup format, unless you absolutely have to.
I say this as a developer who is also a writer. I enjoy writing, but I know many developers don't. And if Markdown makes it easier for them to write documentation, either because they're already familiar with it or because it's just a simpler format, then I'm all for it, even if ReStructuredText might be a bit powerful overall.