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. HomeCapital is India’s first home down payment assistance program.

At HomeCapital, 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 – <rant> 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 </rant>

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
  5. 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.

Why Working Class Indians Still Struggle to Buy a Home & What Can One Do?

There’s room at the top they’re telling you still

But first, you must learn how to smile as you kill

If you want to be like the folks on the hill

A working-class hero is something to be

John Lennon

When you think about it, a working-class hero with a dream to build a home is something to be, especially in the dubious world of rising property rates. You are either of the two – the one who had booked a flat years ago and have lost the hope of waiting for the builder to deliver, and have decided to say goodbye to the dream home that never came to be. Or the one struggling with finances to actually buy a home.

Imagine if you may, a middle-class worker plagued with the thoughts of home loan EMI, house rent till he gets the possession, kids’ school fees, and household expenses – all to be managed in his meagre salary; a seemingly endless loop of payables even before the salary gets credited. Not to mention the big question – how to secure finance to pay off the chunk of the home down payment. Sounds familiar? Perhaps a struggle you yourself might be facing!

With RERA (Real Estate Regulatory Authority) in place, there is some relief to the home buyers when it comes to putting their trust in developers. That resolves the first issue of untrustworthy developers. However, the problem of securing finance still remains the biggest concern.

Today, with subvention plans or no-EMI-till-possession plans buyers are more hopeful. Under such schemes, home buyers are asked to pay some percent (in between 10 to 30 percent) of the amount as the down payment. The rest is paid by a bank to the developer as a loan. While the project is under development, the developer pays the interest on the loan to the bank. The buyer’s EMIs begin only after he gets possession. A great deal, isn’t it? But like all good things, this too comes with a catch. Home buyers need to understand the nitty-gritty of the schemes before venturing into a deal. After all, knowledge is power!

Coming back to the current situation, while no-EMI-till-possession plans resolve 70 to 80% of the problem, the massive 20-30% upfront down payment remains a hurdle equivalent to a massive chunk of an iceberg submerged underwater. Here is where HomeCapital comes to the rescue with it’s Home Down Payment Assistance Program. What this program does is it facilitates interest-free loan equal to the contribution towards down payment which will be provided by the partner-lending institutions in participating projects. The interest is borne by HomeCapital and the principal amount is divided by the number of months to arrive at monthly payments. The program increases your home loan eligibility and makes your home buying faster and simpler. Sounds too good to be true? But it is true. Tried and tested, the program addresses the challenge of the down payment for home buyers, particularly first time buyers from working-class with dreams to have a home sweet home.

To sum up, in the ever-changing real estate market, one thing that never changes is the challenges faced by the home buyers. However, with more strict regulations in place and evolving home finance sector addressing a few of the big problems, owning your dream home doesn’t seem like a far fetched idea anymore. All you need to do is make a smart move to move into your dream home today, rather than five to ten years down the line.