MkDocs or Jekyll for Technical Documentation?

[lana_12]

I work in the Quality Engineering department in Waterloo, Ontario, Canada. There is a lot of information out there, internally and externally, about how we do our jobs. For example, internally, there is JAM, SharePoint, and Wiki.  Externally, I use Google, Stack Overflow, and other technical sites. Having so many sites to navigate, I thought it would be nice to store information in a central location so I created an Information Repository. Not only have does it contain new content but it also references links to all these tools.

The information repository started off as a reference point for new hires and interns,  but it is becoming more than that! It is a great way to share information and fosters cross-training.

After working in User Assistance for some time, I worked on SAP Cloud Platform SDK for Android and saw that they used MkDocs. To begin with, I set up our Quality Engineering documents using MkDocs but later moved to Jekyll.

"MkDocs is a fast, simple static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file." For more information, see the MkDocs website.

Jekyll is simple, static, and is a great blog tool. It is also used for building project and technical documentation. For more information, see the Jekyll website.

Both MkDocs and Jekyll take markdown and yaml files and convert them into HTML. They can both be easily integrated into GitHub and you can use GitHub pages to host the documentation.

I'd like to discuss the benefits and drawbacks of each project documentation tool.

MkDocs

Benefits	Drawbacks
Quick setup time - uses Python, markdown	At that time, no ability to edit a page if you wanted to make a quick change.
Creating a table of contents is simple	Older technology
The search is superior to Jekyll
Running a test server is easier to set up than Jekyll

Jekyll

Benefits	Drawbacks
Has the ability to edit a page on each page	Set up time is longer than MkDocs  (Jekyll, Bundler, Ruby Gems, Markdown are required)
Newer technology	Search is limited to title, keywords, tags and summary
	Running a test server takes more effort if its not your project
	Table of contents can only be three levels

The no "Edit me" was a big issue for me because I wanted it to be as easy as possible to make changes. This button allows a user to edit their current page and make the necessary changes without having to go to GitHub to figure out the location of the page. At the time, "Edit me" went to the project and not the page. This has been corrected.

Edit me

I decided to go with Jekyll mainly for the "new look and feel" and the ability to have someone edit a page. It took longer to get set up but once completed, I was happy that I went with Jekyll! People on the team are adding content almost every day. Here is the landing page of the Quality Engineering documentation:

QE Documentation

 

My next step is to utilize Docker since there are Jekyll Docker images readily available.