Markdown
About
Generally speaking, markdown is the idea of making formatting text more meaningful. The idea was that you could use decorators on regular text that could on their own suggest a particular formatting, but those decorators could be replaced with standard html tags or other formatting so that text could be easily reused in other mediums (web, pdf for printing, presentation, etc)
For the developer, markdown takes the form of documentation, such as the README of a particular repository. As such, we are primarily focused on the Markdown spec used for instance on GitHub (there may be differences in other places, but it's a good start).
Key Concepts
The basic idea of markdown is that it treats the basic text editor as a first class citizen.
So in html, creating a heading would look something like this:
1<h1 id="this-is-a-primary-heading">This is a primary heading</h1>
2<h2 id="this-is-a-secondary-heading">This is a secondary heading</h2>
3<p>This is a paragraph under the secondary heading.</p>
This example isn't hard to read, but there are a few problems with this style. First, unless you know something about html, it's not immediately obvious that the headings are a different weight. Second, it's clunky to write. Sure, a decent ide can help generate the closing tag for you. I could omit the id from the heading tags and it would display the same in the browser (and be easier to read), but then this and the next example wouldn't be equivalent. The id makes it so links can be made to that heading.
In an effort to make html easier to generate, markdown was born. Here's the same example:
1# This is a primary heading
2
3## This is a secondary heading
4
5This is a paragraph under the secondary heading.
You'll notice, there's not really anything extraneous to type. Also, the symbols that are there lead you to believe there's some sort of weight difference between the two headings and then the regular text below. It feels meaningful.
This is what I mean when I say the text editor is a first class citizen. Sure, if you open this up in notepad you aren't going to have any fancy links, but it's still very understandable. It's also very easy to type.
Honestly, markdown can be used to generate links, tables, embed images and a bunch of other things, that are much easier to write than the html they replace. But the best part about markdown is, you aren't really giving up any features.
If you come across a situation where you need to use html, feel free to drop it in. You won't get the nice reading experience in a text editor, but whatever you are using to convert to html will handle it just fine.
Use Cases
Well, the place I use markdown all the time is in git. In any code repository, it's good practice to include a README.md file. That becomes the first page your audience comes to when they browse your code on GitHub or whatever web repository solution you use.
Another place I use markdown is in data science tools such as Jupyter. Jupyter notebooks provide you with the ability to intersperse markdown cells amongst your code, creating the opportunity to create detailed notes or even write up a research paper inline with your program.
Then this blog is written in markdown. There are several different website engines that take advantage of markdown to make it easy to generate and maintain a website. Jekyll is the one I use.
Gotchas
There are many different dialects of markdown or mardown like syntax. For my purposes, I stick with the GitHub Flavored Markdown Spec, listed in the Reference section below. You may find one that works better for your needs. Feel free to explore!
Recommendations
- Markdown All in One by Yu Zhang - A VS Code extension that I use for one important purpose, automatically updating a table of contents. There are some places (I believe VSTS is one) where if you put
[[TOC]]in your markdown it'll automatically generate a table of contents from the headings. And while that's cool, it's not consistent. This way, as long as you are using this as your IDE, you can plop in a ToC and it'll automatically update. - Markdownlint
- Pandoc - A utility that converts markdown or markdown like syntax into all sorts of formats (Word, pdfs, emacs org files, epub, etc). Awesome utility that can save you if you need to update a bunch of files that aren't otherwise easily converted.
- vscode-pandoc - A VS Code extension that gives you the functionality of Pandoc in the command pallete. It's a little weird that the oringinal extension was abandoned but the old maintainer blessed a new version, but hasn't retired his old one.
To Research
- Paste Image - this extension is a little too black magic feeling- I want to read more about it, but it could be very handy if you have the need.
Justification
There are a myriad of resources out there on how to become a developer and each one usually is tied to learning Python or Java or whatever. My goal in this series is to not replace those- you do need a first language that you start your journey on. My argument is there are things you need to know, that will significantly increase your value as a developer that your course on Scala isn't going to teach you.
Here's my argument:
- Code serves two purposes. It tells a computer what to do, but mostly it is about structuring logical commands so that other developers can understand it.
- Most of your time will be spent maintaining existing code, not writing new code.
- Communication (written) is one of the most important skills you need to have with other developers, but more so with the business.
- The best place to keep information is with the code itself (your ticketing system may change, but your README will chase your code around till the end of time).
- Markdown is easy to generate and easy to read.
- It may not have the bells and whistles, but it's very universal.
- You aren't doing your job as a developer if you don't document.
I'm not saying my argument is perfect, and honestly if you disagree with me I would love to hear your argument. Unfortunately most of the arguments against it have been that we don't have time, it's hard to maintain or that some other system is the way we operate.
To the time argument, I can to some extent understand. Today, it can feel like you will remember exactly what to do and why you made some decision. But if you have been working on something else for say a year and then have to jump back into your code, are you going to remember enough details to troubleshoot a production issue? The reality is that not all time is the same. While it feels expensive at the time, development time is cheap. I mean you don't want to tie up other teams or anything, but it's the best opportunity you have to capture the information between your ears. It's not only fresh, but you haven't deployed anything yet. In an ideal scenario, initial development is a one time event, but that software could have a useful life of months or years. If you can invest a little time now, but collectively save time in the future, isn't paying down the technical debt a good idea?
To the system of record argument, what happens if your system of record changes? Are any links you included going to still work? What if you move the git repo? What if you lose the system of record? I feel like this argument is more about resistance to change than anything well thought out. If demanded, is it horrible to put a link in the system of record to your git repo, or worst case copy the text in both places? The good news about markdown is that it's pretty readable just as text, so I wouldn't lose any sleep over doing a straight copy and paste to this other system. If you want to get really fancy, use pandoc and convert it to some other format that is compatible with this other system. Realistically, I would be suspicious of this argument in the long run.
To the it's difficult to maintain or too long to read argument, I just don't believe it. If you are building an open source project where you are really crafting a marketing piece with your README because you want people to contribute, I completely support you that putting a bunch of stuff in your README may not be a good idea. You can just make a docs folder instead and fill it full of all the details you want. Here's the thing with this argument. space is really cheap and searches are really good. If you find you need to go back and edit the readme on the next commit, please do so! It's so easy to see a diff in git that I feel like it's better to start with more information and pair it back, rather than to have not captured it at all. I do feel like you should remove wrong information, but even keeping a brief history of the project I think is a fine idea. I'll build out an example structure later, but I think the main takeaway in this case is that it's best to commit the idea so you don't forget or lose it.