Documentation as Code

The older I get the more I have come to despise Microsoft Word for technical documentation. In my world, documentation requires constant updates and periodic review and revision and when things go bad in Word which invariably happens, it goes really bad. Throw in multiple editors and multiple revisions over time and you usually end up with something that starts to lose its formatting over time and when your heading structure and auto-numbering breaks, well then all bets are off and sometimes your better off to spend the time and rewrite it.

On top of this Word has its own priopriatary format meaning if you get a document corruption, well good luck to you. Over the past year or so ive been using Markdown as my weapon on choice when it comes to documentation and i’m on a mission to convert others. Its text based, easy to read, easy to convert to other formats like PDF and when coupled with GIT gives you an exact change record if you need to go back in time. No more fumbling your way through Word and all its unnecessary features for this use case. Lets face it, WordArt should never come to mind for your documentation.

If you have not already gotten yourself a copy of VSCode, do it. I literally use it everyday and with its ability to be enhanced with extensions, all your wants in a text editor and IDE are covered.

Heres a cheat sheet of most of the functionality you are going to need when documenting as code:

Github/adam-p/Markdown Cheatsheet

This document covers all the markdown codes you will ever need!

• Headers
• Bold/Italic/Strikethrough/Horizontal Rule Formatting
• Ordered/Unordered Lists and Bullet points
• Inline Code and Code Blocks
• Tables
• Linking Images / url’s
• Quotes

And if looking at text formatted text isnt appealing and you need something that looks a little more “presentable” then this is where VSCode has an extention that covers you. From your Extensions shortcut (or Ctrl+Shift+P, type >extensions: Show Installed Extensions), search for an extension named Markdown PDF by yzane. It has 500k+ installs.

Once installed, you can Ctrl+Shift+P, type Markdown PDF and you can export your markdown. How neat is that?

And opening up a preview pane using Ctrl+K, then V you can see your not so fancy markdown text in a formatted way side by side. This feature comes in handy especaially when working with Markdown Tables which the readability suffers in pure markdown. The images are supposed to be side by side, but it doesnt translate well as a super wide image here on the blog.

With Markdown:

With Markdown Preview: