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.

[Abinathsiva]

Nice article...

[lana_12]

Thank you!

[lbreddemann]

Thanks for the nice read and the interesting look into your and your team's work.

Sadly, the github page referenced is SAP internal (.sap.corp -domain is not reachable from the "outside"), so only SAP-employees will be able to see it.

If you find a way to share this on a public github account, that would surely be interesting.

 

[lana_12]

Thank you for your nice comment Lars. I will need to update the post to just show a screen shot instead of the link.

[former_member774344]

Great article. Did you use an out of the box theme or your own from scratch?

[lana_12]

Thanks Nick.  I used an out of the box theme for MkDocs and when I was working with Jekyll, I used a pre-existing one (that I inherited from another group).

Hope that helps.

 

Lana

 

[former_member784215]

I'm not aware that three levels of heading is a limitation of Jekyll per se (assuming you mean the left-hand navigation bar). I think Docker's documentation is built on Jekyll and the navigation tree goes to four levels occasionally.

I like MKDocs, but my only issue is that it doesn't scale to large sites. The navigation schema is baked into the template and gets quite limiting once your site grows to hundreds of pages. Whereas Jekyll's templating system is much more flexible. Good choice for small-to-medium projects though.

[lana_12]

Hi Paul,

Thanks for your comment.   Yes, I did mean the left-hand navigation bar.  I think the level of headings  could have been a limitation at the time that I built the documentation.

I am searching for it in the documentation and do not find anything and can't not find the specific page it was mentioning before. Perhaps it is the theme that I am using with Jekyll. I also looked at this page https://idratherbewriting.com/documentation-theme-jekyll-next-version/.

Thanks,

 

Lana