Don't use Markdown for technical documentation

If you've written technical documentation, you'll know about Markdown. It's easy to get started with. It's easy to write. It's supported by just about any and every platform and service you're going to use, e.g., GitHub, GitLab, StackOverflow, Reddit, LinkedIn, and numerous other services.

Despite that, it's not the best choice for technical documentation! However, there are two formats: AsciiDoc and reStructuredText, that are. What's more, these formats were designed with technical documentation in mind.

In this episode, I step through my frustrations documenting software with Markdown, and give a healthy plug for why you should use AsciiDoc instead. It's loads better and far more enjoyable to document your code with.

Links from the episode

• AsciiDoc
• reStructuredText
• GitHub Flavoured Markdown - Basic writing and formatting syntax
• R Markdown
• Markdown Extra
• CommonMark
• Markdown Guide
• Aaron Swartz
• John Gruber

Want to grow your knowledge further?

Check out the books below, where you can grow your web development skills in a very focused, very hands-on way.

• Deploy with Docker Compose
• Mezzio Essentials

Hosted and produced in Bundaberg by: Matthew Setter.

Website: https://matthewsetter.com.
Follow me on: LinkedIn.

If you like the podcast, and want to support it, how about buying me a coffee?