Working with markdown and gitbook

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?

Working class

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.

Solving the problem of Discovery

The real problem that Google solves, is the problem of availability. When you have a problem and are searching for the solution, Google provides you with a list of most likely content that can address the problem. The problem is created by information asymmetry. You just don’t know and are willing to try out or read about the different solutions.

However, over a period of time this has turned into a problem of plenty. So many content providers are creating content for the average internet user, that the options tend to give all the creators a sliver of traffic. This has led to a bulk of copy-cats and me-too content providers eyeing for their search visibility. So much so that one of the default rules of inbound marketing is to start a content creation cycle and hope that you keep attracting traffic via Search.

What can new brands do?

Stay away from the whole attack of the clones! All marketers would swear on grabbing the attention of the customer as many times as possible in order to drive a higher brand share. However, at the cost of what?

Instead of creating very similar content? How about solving things that matter instead?

How about identifying a niche area where there is a genuine need and people are struggling to find answers?

This might seem contradictory to what I was saying, but once a brand (or a team) starts engaging with the customers, then you start seeing a slew of issues that no content provider is addressing. Talking about these issues and solving them via your product or service is a far better way to get discovered, rather than to keep talking about how your me-too offering is different from the competitor’s me-too offering!

tl-dr;

Engage with customers to discover what message and positioning you need to take when it comes to working in a crowded market.

Comfort Zones

In case, if you haven’t really been following my blog, I generally tend to write about tech, games, some personal thoughts, some thoughts about my work at 13 Llama and some analytics.

What I do not write about is Design … be it any design. Systems design, Visual Design, Brand Design … even solutions design. I know for certain that I have a certain unhealthy fear of engaging with the design. So much so that it has now become a mental barrier in my head. Staying away from creativity isn’t necessarily bad since we do a lot of analytical and logical work. Having said that, breaking down problems into smaller bite-sized tasks is now a child’s play and there has become a comfort zone. So much so, that over the past few months I had started to think that we should focus on driving more business in these areas.

What does one do when one doesn’t have an option?

Of late though, some of the mandates we have been getting involved us having to work with and also having to define the design specifications. Some of our new team members were pretty gung-ho about working on design specifications instead of a pure play numbers game.

To add to that, at pretty much the same time, we had a couple of our main clients request that we get involved at a higher level and help guide the marketing briefs.

We could have chosen to keep focused on the analytics niche and not step up to the mantle. However, we decided to step out of our comfort zone and things have been taking an interesting turn.

Stepping out of comfort zones

This often involves stepping into a chaotic situation, spending some time taking stock and then working on multiple fronts and more often than not in an iterative manner. From an engagement point of view, it takes a special sort of client to work with. An organization which understands that is an organization that is also in a sense working out of its comfort zone.

This also means that the team which is actively engaged in stepping out of its comfort zone is very very focused on the purpose at hand.

Instead of worrying about things such as appraisals, office times, leaves and petty office politics, the team is then focused on doing what it takes to get the job done. The line of comfort just disappears and shit gets done.

Organizations and comfort zones

For a lot of organizations, functional teams end up becoming comfort zones. An example of this is when there are functional silos in a firm and cross-functional exchanges do not happen as smoothly as expected. This is when both the functions engaging are not stepping out of their zone of comfort. Unfortunately, we have all experienced the adverse effects when customer-facing teams do not step out of their comfort zone.

This severely impacts their ability and sometimes even the intent to engage. Symptoms of this condition are cases where the customer-facing teams cite company policies, or often play the victim, or end up misinforming or lying to the customer. This builds a trust deficit within and without the system.

What can organizations do?

Foster a culture of experimentation and over-delivering value. Sometimes force teams to work outside the zone of comfort. Align teams to the grandiose scheme of things and how their mundane job is, in fact, a purpose-centric activity and not a functional silo.

As a concluding note, assuming people are willing to often step out of their comfort zones is such a positive mindset that the rewards of the mindset alone are worth the efforts of stretching one’s boundaries. Over the past few months, I have seen my fledgling teamwork outside their comfort zones, get over their initial mental barriers and come out for the better. The decision to step out of my own comfort zones has been definitely worth it!

 

The Case of the missing Engagement Glue

This is a narrative to highlight how we somehow miss the element of human engagement in our day to day interactions. In an economy such as India, where 56% of GDP comes from services – missing human engagement seems like a big concern for me.

The incident

In the month of December 2016, my parents and I decided to go to Gwalior. The reason was to attend a friend’s wedding. I figured that we would get some time to look around the city – as well as some time off from work. I did not wish to travel via train (since its a 20 hour journey). Thankfully we had enough time to plan ahead, so we bought tickets off Cleartrip.com (this being one of my favored sites purchase travel tickets – both air and rail).

Flash forward to December 9th, the date of the flight. We huddled up to the T2 terminal in early morning – hoping to reach Gwalior just before lunch. It’s not as if we had planned this in detail – it’s just that there is just one flight that goes from Mumbai to Gwalior. That flight being an Air India one, and that too once a day. So much for choice!

1 hour before the flight, we are checked-in and sitting at the boarding gate. Most of the other passengers have started showing up. My initial suspicion of this flight being empty are quickly put to rest as I count around 50 odd passengers at our boarding gate. Just then, Air India announces that the flight might get delayed by an hour or so – since there is fog at the Gwalior airport. Some folks have started grumbling, and the elderly lady sitting next to me is concerned that she may not reach the hospital in time.

An hour later, the flight is promptly announced cancelled and the hapless attendant at the boarding gate points the irritated passengers towards the Air India desk. Fortunately, I am quickly able to figure out the next steps in flight cancellation and I was able to get the entire PNR of both the flights cancelled (since it was a round trip – this was done de-facto by Air India when they cancelled my onwards journey!).

At this juncture, I realize that reaching by flight is impossible for my parents. I could have gone via Delhi or via Bhopal, unfortunately Air India was not willing to transfer my ticket to another firm’s flight and wanted me to wait for their next empty flight. Somewhere, the Air India helpdesk just stopped being customer friendly (who wouldn’t when faced with 50 angry customers all shouting for alternative flights), and started quoting the policies.

Cancellations and refund

Having my flight cancelled, I got on a call with Cleartrip.com and confirmed the refund amount we would be getting. So for spending roughly 35k for the tickets and wasting so much time, we would be getting most of that amount back. The attendant was super friendly and seemed to grasp the situation – he promptly had an Air India customer care operator on conference call and asked for the full refund. This process amongst the chaos took 5 hours or so. The customer care operator from Air India – Manoj, seemed diffident at first, however he agreed that I would be refunded in full when he learnt that it was a single PNR. The Cleartripper must have been trained for such situations – so he verified this twice on the call. Then he assured me of the refund and asked me to return back home and proceeded to cancel the tickets. We reached home in the evening, having deemed that some time and money had lost and we would be missing my friend’s wedding (sorry Jay!).

After the customary vows of not using Air India ever, and praising Cleartrip for their super awesome service, I went on with life. I was informed by Cleartrip that this refund would be processed in 25 odd days – since I did not have an endorsement copy ready.

Dec 9th: Email from Cleartrip Team
Dec 9th: Email from Cleartrip Team

Since, I did not have this aforementioned endorsement copy, I replied back stating that I’d rather wait for Cleartrip to do the same for me.

The Engagement Gap

Now, starts the real story. On the 5th Jan (almost a month after the flight was scheduled), I receive this email from Cleartrip.com.

Jan 5th: Email from Cleartrip Team
Jan 5th: Email from Cleartrip Team

I remember a cold dread going through this email. Fortunately, I remember that there was a recorded conversation between the three parties (Cleartrip, Air India and I) – where the Air India operator had confirmed and mentioned on record that the refund would be processed in full. So how can they go back on their word?

I picked up the phone and spoke to a Cleartripper about the same. The Cleartripper took some time understanding the issue, went and verified that such a conversation existed, and then asked me about the endorsement copy. I do not know how this looks like so I asked them to arrange it at their side (they claimed they could take care of this, however, it would take their 20-25 more days).

At this juncture, I trusted Cleartrip and said that the wait would be fine (since I have already waited month, another 20 days may not matter).

The Engagement Gap widens

On the 14th of Jan, I receive this email –

Jan 14th: Email from Cleartrip Team
Jan 14th: Email from Cleartrip Team

This is where I lost all hope of getting any money back. A cool 30k down the drain. Thankfully, it was a Saturday – and I had some free time on my hands to get into the heart of the matter.

I got onto a call with Cleartrip and 15 minutes later had explained the matter to one more Cleartripper (so now at least 3 of them know about my issue). In classic textbook style script, she proceeds to assure me that they will look into it and will get back to me in some time.

This is where I lost all trust that Cleartrip would indeed solve the problem. Please note, I am not bitching about Cleartrip or Air India – at least not yet! So, I decided to push for a turn around time. I was informed that the concerned person would contact me in an hour’s time.

An hour and a half later, I call Cleartrip to follow-up. A separate person this time, another round of explanations go and this chap also placates, re-assures and promises to get back. I refuse to hang-up, and call him on this point that everyone promises to get back – but no one does. At this juncture, the fine chap that he is informs me that it would be simpler if I had the endorsement copy in place.

Wait, what? So I waited 35 days for Cleartrip to get something which I am not supposed to get. Why did they not say the same in the first place? Why offer to do this if they do not really engage with the problem.

Look who’s talking!

At this point, I realized that screaming or ranting this won’t solve my problem. If I do not chose to do something about this state of issues, then my money is most certainly lost. Grumbling obscenities with Air India, I head on to T2.

I reach Air India’s office and explain that I need an endorsement copy for the flight number. The officer asks me the PNR number which I provide. She looks at the date for a minute and goes to the senior officer. He proceeds to process this (while handling 2-3 other emergencies), he asks me why did I not get this on the day of the flight itself. I narrate the entire incident to him and he gives me the copy in 10 minutes flat. My impression of Air India stands changed.

While this was happening, the Cleartripper (the last one) calls me and suggests me to get the endorsement copy to process the refunds. I email him the required photographs of the copy and there ends the matter.

As I was typing this post, I thought it might make sense to double check with Cleartrip. True enough, they haven’t yet received the endorsement copy from me. It seems that their CRM (which is Salesforce) is not configured to receive attachment to replies, and expects me to send a separate mail (not as part of the mail chain) to them. I send this, and receive acknowledgement of this. I have been told to wait for 2 days on this for any further update. There is a trust deficit in my mind when I talk about Cleartrip … a site which I have been using for around a decade now.

So who is not engaging here?

I don’t know! Is it Cleartrip or was it Air India that f**ked up?

Or was it me who simply did not chase these matters?

Does it have to be this hard? In this mess of exchanges, there were so many opportunities for one human to go the additional distance and close the gaps.

  • Air India could have given the endorsement copies the minute the cancellation was announced.
  • Cleartrip could have fetched this themselves and not kept buying time
  • I could have chased after both Air India and Cleartrip and addressed this matter. I certainly plan to do so now.

The Engagement Glue

If I have not lost you by now, most certainly you are piqued by what I mean by The Engagement Glue.

There are 4 basic interchanges happening here –

  1. Purchasing the ticket on Cleartrip. I think they have nailed this experience.
  2. The actual flight. Air India could not help here, the Gwalior airport is controlled by the army base and it shuts down operations after 3pm. The fog was a natural act, and could not be helped.
  3. The cancellation process. This is where a clear engagement failure happened. Air India officials should feel more concerned about the emotions that a passenger goes through, and not cite policy.
  4. The refund process. Another engagement failure, Cleartrippers should look further than providing text book responses. The user should also actively track this (I am the user), it’s his money after all!

In the last two points, there was a need to bridge the engagement gap with some understanding. With some Engagement glue. Human empathy could have been that glue.

Conclusion

At the end of this fiasco (when it ends!), all I want to say is that the trust with which I used to operate is lost and that could have been saved simply by being a bit more human-centric.

I see this in a lot of services, the great service providers go that bit extra and ensure that everyone around them feel customer delight.

The damn thing doesn’t end here!

26th January 2017. This addendum after 10 days.

After waiting for Cleartrip to respond, I called their Customer Care team up. It seems that their representative had forwarded the matter to the wrong team! I am being told to wait for 2-3 days more, guess I will keep this updated and see what comes of it.

2016 – A Year in Review

As the year whittles down to a close, I’d like to look back towards both the highs and the lows of this year. Hopefully, I can then celebrate more such highs and try not to repeat the mistakes of the past year. Of course, it’d be great to bury all the proverbial hatchets and move on – perhaps this post (or if not this) is just that!

Read more2016 – A Year in Review