In today’s environment, we have an embarrassment of riches when it comes to documenting our applications. We have a multitude of word processors, websites with word processors built in, wikis, and notes applications galore.

So you may be wondering, is there even any point in talking about ways to document your application? I think there is. In this blog, I’ll share my documentation tool and how and why you can use it in your own projects. It’s called Markdown.

Where to Document with Markdown

I’ve had a couple of projects where I wanted to keep documentation for the project as close to the code as I could. The documentation can, and probably will, live on a team website as well. For easy access, though, I wanted it right where the code lived – preferably in the same version repository as the source code. Being able to read and edit the documentation with the same or similar tools and to track the version differences just as we do our code would be a huge bonus.

The obvious choice in this instance would be plain old text, but plain text does not allow for a rich experience. So for situations like this, I would like to suggest, or possibly introduce you to, Markdown.

What is Markdown?

For those that don’t know, Markdown is a plain-text, structured language for creating HTML documents. It also functions as the application used to create HTML documents from Markdown documents.

Markdown is used in several places, including GitHub. Github provides some great guides on how to use Markdown if you want to check them out.

I find that Markdown has the benefit of being able to use any text editor to create or edit your documentation, but unlike plain text, the end product can be a rich document, complete with images.

Images

In many cases, our application documentation could benefit from the addition of some type of image – for example, a Software Architecture diagram or a screen shot.

The different flavors of Markdown each handle image attachments in their own way. I prefer to leverage something I see as a strength of Markdown, the ability to include HTML tags directly in the Markdown document.

For instance, one of the screen shots I include later can be written directly in the Markdown document as:

Let’s run through a quick example to demonstrate this. My example centers around inserting Architectural documents into our Markdown document. I used MockOla to create a diagram.

On a side note, if you haven’t already, I suggest checking MockOla out! MockOla is a 2D drawing tool built by Keyhole Labs, and it’s super user friendly. If you need any sort of software architectural image (such as a UI wireframe, UML diagram, or other architectural design images), MockOla is a great tool to check out. Take a few moments to mess around with it!

Back to the example! The first step is creating the architectural image I’m going to insert into our Markdown documentation. Like I mentioned, I’m using MockOla:

Here is the resulting output:

After saving the above output as a png to my desktop, I can easily insert it into Markdown using HTML.

Layout

Ultimately, the purpose of this post is to provide you with another tool for your programming tool chest. Additionally, as I mentioned before, another one of my goals is to end up with a document that is as close to the code as possible. So, where do we put it?
We have a few choices. There are plugins like NetBeans and Eclipse for different IDE’s that will make writing Markdown easier and closer to the code. Also, we would like our build tools (Gradle or Maven) to have access to Markdown documents.

If you do not need to keep your deployment package small, you can put all the source documents in your resource direction, like this:

However, if you do need to keep your deployment package small, you can use the test tree or create a documents tree the build tool will ignore instead.

This structure will also allow you to check the documents into your version control system. You can use this to easily track the changes to your files – in the same way you do for your code.

Building

When you need a rich visual representation of the page, run Markdown DocumentingWMarkdown.md > DocumentingWMarkdown.html. . This will compile the Markdown document and add links to the attached images.

Markdown will output the results to the command line, so we use > to redirect that output to the HTML document. This document can then be displayed in a browser. I have had great success in copying that page and pasting it into a Word or Apple Pages document. A quick overview and touch up on the look and feel, and it’s ready to publish.

Conclusion

In conclusion, Markdown is a great tool to use for documenting. I would encourage you to test it out for yourself in your next project!

And it doesn’t end at documenting! There are many, many practical uses for Markdown. In fact, I created this blog post in Markdown using the Vim text editor and then copied and pasted the result from the Safari browser to a word processing application for final look and feel changes. Lately, I have also been using Markdown to create outline handouts for classes I teach each week.

I hope this blog gave you an introduction to Markdown and one possible use for it. Consider this a suggestion for another tool you can use in your programming arsenal!