{"type":"rich","version":"1.0","provider_name":"Transistor","provider_url":"https://transistor.fm","author_name":"Web Dev with Matt","title":"Don't use Markdown for technical documentation","html":"","width":"100%","height":180,"duration":1613,"description":"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 episodeAsciiDocreStructuredTextGitHub Flavoured Markdown - Basic writing and formatting syntaxR MarkdownMarkdown ExtraCommonMarkMarkdown GuideAaron SwartzJohn GruberWant 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 ComposeMezzio EssentialsHosted 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?","thumbnail_url":"https://img.transistorcdn.com/ErogIDxqOFQN8RVLHvl3XfLOJ_kkPEv3rY7vQp7PDxI/rs:fill:0:0:1/w:400/h:400/q:60/mb:500000/aHR0cHM6Ly9pbWct/dXBsb2FkLXByb2R1/Y3Rpb24udHJhbnNp/c3Rvci5mbS9zaG93/LzEyNjc1LzE2NzIz/ODI3ODYtYXJ0d29y/ay5qcGc.webp","thumbnail_width":300,"thumbnail_height":300}