Working with markdown and gitbook

For those of you who don’t know yet, I have shifted tracks to heading a tech team in a start-up. This firm focuses on helping first time home buyers with the largest hurdle in home buying, the down payment.

At Homeville, one of the immediate challenges that I had to face was to understand a myriad of requirements from speaking to the operations team, to the business analysts, to the developers, to some of the customers and even to some of our investors.

Since, the approach is that of a technology platform, it also means that the team had to start worrying about multiple systems all at once. Deciding to move away from one huge monolithic system to a micro-services based architecture was natural.

How does one manage loads of Micro-services?

A major challenge with a spread of micro-services was that the management overhead of systems went up. Different services were in different repos, in different languages and hosted in different methods. Yes, there was an API gateway on top to present a uniform access method for all, but the code management and documentation was a challenge.

Thankfully most popular versioning systems have solved the code management issue. One of the first steps I initiated with this was using the README.md to quickly jot down what the service is supposed to do, and how it functions. This was created more from the point of a new team member who wants to get started with the respective service. You need to be comfortable with Markdown for this. I’ll get to markdown in a minute, but this was a great starting point for me to understand what a developer really needs in the documentation.

As a person overseeing multiple services, it was essential for my team members to quickly pick up the bare essentials and use the documentation available. Having a small entry point in the repo is a perfect way to give access without creating too formal a structure. My choice of working with markdown was made.

What is Markdown?

In case if you do not know what this is, then you mostly haven’t edited a wiki. Markdown language is a super lightweight language that allows one to quickly convert the text into a rich formatted document (such as HTML, PDF, etc). To read more about this, head on to the Wiki on Markdown.

Try practicing using Markdown for some time and you will realize its almost as simple as using notepad or gedit to take down your notes. It also helps you to create a more complex structure and is super flexible for future use-cases.

Generating a usable README.md

For those of you who want to try this out, hop on to Make a README and see the basic placeholder sections needed to make a developer friendly file.

I had by this time quickly written these files and was happy that at least I had some formal documentation available in a system that was fast growing. A side note here – In most rapidly evolving systems, people often take decisions that they regret later on. This technical debt although is meant to be avoided, but often it just can’t be avoided. As long as you are willing to come back and clear the debt, it’s fine. You could re-think your approach and do it faster in a correct fashion – but then you need to be a lot more mature and I just don’t see that developer maturity yet. This side note will need to be expanded into a separate post of it’s own

What to do with a cart load of README.md files?

Quickly, I had many individual standalone files sparsely connected to each other. While this was sufficient for a developer to get started, this did not fully cover the breadth and width of the system.

This is where my past experience of working with the WordPress India community helped. The community is building an independent document made of such .md files using gitbook. Gitbook used to be a CLI based command that you could install on your machine and use to build a developer website. This using the very .md files that I now had.

At the time of writing this post, the gitbook CLI is available on npm, however, do note that the site now talks about a version 2, which is not a CLI based offer but is more of a SaaS product with a freemium offering. You could also look at some other alternatives to do this, but the ease of use of the gitbook CLI is to be applauded.

How to get started with gitbook?

1. Head on to the npm page for gitbook-cli and install this first.
2. Create a new folder and in the console hit gitbook init
3. Answer the questions and create your first markdown file
4. In the console hit gitbook serve and in your browser go to http://localhost:4000

That’s it

Core concepts

Keep in mind the following things –

• The SUMMARY.md maps to the sidebar on the left hand side. This can be styled and the content of this file pretty much decides the navigation of your gitbook
• gitbook is extendable through the config file – book.json, not just in look and feel, but also using plugins. My must plugins are – [“collapsible-chapters”,“insert-logo”,“image-captions”,“tbfed-pagefooter”,“copy-code-button”,“ga”,“sitemap”,“mermaid-gb3”]
• Create sub-folders for different modules/services
• Have a list of all entry points in SUMMARY.md
• Maintain a CHANGELOG.md to have a history of major changes made
• When a particular module becomes more complex, divide that into more parts and put those parts into nested folders. Do not forget to update the links in the respective .md files
• Make the respective indents in the SUMMARY.md file as well

Building your gitbook

You can even host this somewhere (such as an S3 bucket or a static hosting). Simply execute the following command –

gitbook build

This will create a new _book folder in your gitbook folder. Host this as the static site.

That’s all there is to it. A simple and easy way to manage an evolving set of markdown files using gitbook.