General

Functional documentation with markdown and version control

Leon Hassan

Oct 24, 2017 • 3 min read

One issue I've seen come up again and again in projects I've worked on is keeping track of documents and tracking the changes made to them. At the Capgemini Engineering blog we write posts in markdown and put them in version control, this makes it really easy to comment on drafts and help build the best post.

Why isn't this done for documents such as functional specifications?

What is Markdown?

Markdown is a way of marking plain text to create various formatting changes e.g. **bold**, *italics* comes out as "bold, italics".

Using a text editor (such as Atom or Brackets) you can even get your document to display your formatting changes as you write. There are even plugins to generate a pdf from your markdown too such as Markdown PDF for Atom.

You don't need to use a specific program to write in markdown though, it's just plain text. Notepad/TextEdit will be fine! There are even online editors such as Dilinger that will give you a nice editor and save your documents, you can even save your markdown documents in Google Drive!

There are a number of flavours of markdown, which means that they differ every so slightly from each other. But this doesn't matter too much because the most popular form of markdown, CommonMark and many other popular flavours let you use whichever version you like to achieve the desired format. e.g. _italics_ and *italics* are both valid markdown for italics.

Markdown cheatsheet

It's all good and well telling you about how cool and easy markdown is, but getting started in new things is very daunting! So here's is a little cheatsheet for your new markdown adventure.

Headings

H1: # Header 1
H2: ## Header 2
H3: ### Header 3
H4: #### Header 4
H5: ##### Header 5
H6: ###### Header 6

Further than this won't work reliably, it's also probably worth breaking your document into a number of them if you're consistently using 6th level headings though!

Text styling

Links: [Title](URL)
Bold: **Bold**
Italicize: *Italics*
Strike-through: ~~text~~
Highlight: ==text==
Paragraphs: 1 blank line space between paragraphs
Line break: Add two spaces to the end of the line
Lists: * an asterisk for every new list item.
Quotes: > Quote
Inline Code: `for (code in markdown)`
Horizontal Rule (HR): ---

For horizontal rules you can use more than 3 -'s, it doesn't matter as long as you have at least 3!

Images

Image: ![This is a alt text](https://link.to/image)

Isn't version control for techies?

Things like Git and Subversion probably aren't things that non-technical people are used to using, I bet even thinking about it makes you want to turn off!

But have no fear, you don't need to be a master of the technical arts to use source control.

What is version control?

Version control is exacatly what it says on the tin, it tracks changes to files so that you have a complete history of changes to all your files.

The benefits of version control are pretty much endless. You can see who submitted which changes, you can have people work on personal versions called branches and then have those changes added to the document after review. You can even add comments and to-do's to the document, allowing people to check them off which each change.

Version control work by tracking the changes to plain text, which is why markdown is so great for version control. You don't get all the technical issues that come with big binary files such as word documents!

How can I use version control?

I get that for people who haven't used it before, this can be incredibly difficult to get involved in. So I recommend a version control Graphical User Interface (GUI), which are different for each version control software. For instance GitKraken for Git and SmartSVN for Subversion.

GitKraken screenshot

I know the above screenshot is a little busy, but a quick read of the 'Interface Basics' section of the GitKraken Getting Started guide tells all.

GUI's take away a lot of the pain for technical and non-technical users, it abstracts the logic and makes it look and feel intuitive. No more running a half dozen different commands in the terminal with a bunch of different arguments.