{"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.\nDespite 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.\nIn 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.\nLinks from the episodeAsciiDocreStructuredTextGitHub Flavoured Markdown - Basic writing and formatting syntaxR MarkdownMarkdown ExtraCommonMarkMarkdown GuideAaron SwartzJohn GruberWant to grow your knowledge further?\nCheck 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.\nFollow me on: LinkedIn.\nIf 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}