Goodbye Markdown

Over the last couple of years I have used Markdown a lot. Content on this blog is written using it, Github has A-grade support for it, etc, etc. In general, it's a nice unobtrusive way to write prettier than plain-text docs.

Now, though, it's time to move on.

You see, Markdown just doesn't scale. It's absolutely awesome in the small, but when you need to do something that takes more work, it really falls down. Don't believe me? Try writing extensive technical documentation - say anything that requires linked information, potentially reusable snippets, etc.

While there have been some valiant efforts to extend markdown, I believe doing so is probably time wasted. You see, it's already a solved problem.

After just spending a day or two with reStructuredText and Sphinx it's clear that these tools are built to scale. On the flip-side, they do feel daunting to get started with, and perhaps at first don't feel quite as natural to write in. Still, I think it's definitely a case of short term pain, for long term gain.

Combine the power of the tools with great online resources such as Read the Docs and I would say you have a recipe for success. Just have a look at the quality of the documentation for a project like Celery. Wow.

I would also say that Sphinx feels strongly geared towards use with Python. After poking around a bit though, I found it does a bang up job with other languages too.

Over the next few weeks I'm going to make a good effort towards documenting my experience with documenting JS projects with sphinx at sphinx-js-howto.readthedocs.org. If you have already been using Sphinx with JS projects, then if you could drop tips here or hit me up on twitter that would be awesome.