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
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.
Check out the books below, where you can grow your web development skills in a very focused, very hands-on way.
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?
★ Support this podcast on Patreon ★
Follow me on: LinkedIn.
If you like the podcast, and want to support it, how about buying me a coffee?
