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.

Data, Reporting and doing what’s right

Data is being used to showcase that vaue has been generated. In order to do this, the most beautiful reports have to be eeked out. Now if you are a follower of Avinash Kaushik and don’t like data pukes, then you would be aghast at some of the reports that agencies in India tend to dish out.

I was, and 13 Llama Interactive was born out of that need to do better at both data driven marketing and reporting with transparency.

The road to hell is paved with good intentions

If you’ve been providing paid marketing services to clients for any extended period of time, you know that every person you work with has a different level of online marketing knowledge. Some people might be experienced account managers, others might know basics, while others still might not know the industry at all. It can be easy…

via 5 Agency Reporting Tips to Prove Your Value to Clients — WordStream RSS Feed

Apparently “agency reporting” is a thing. This is where every week or every month, the agency that is handling the brand account (or the performance account if you may) sends across reams of PDFs (or excel sheets) that’s meant to prove that whatever hair brained plan that they had cooked up the last period has worked.

The most common method to justify existence is to keep throwing boatloads of data reports from all tools and then talk about worthless metrics. Each of these tools mentioned in the article that I have shared helps agencies do this at scale, effortlessly.

Is too much data a bad thing?

It can be. If all that data is leading to Analysis Paralysis … or if it leads to falling in love with data analysis itself and forgetting real business outcomes (the reason why you got money for funding the collection of all that data).

If no one is using this mountain of data for solving problems, then it’s better that the data not be collected at all.

Yes, you are letting go of possibilities, but so be it. The damage to the business by wasting resources on gathering more liabilities instead of assets is much worse.

That’s what creates a paradox. Should we or shouldn’t we collect data?

Here’s a great video from Superweek that makes the case pretty well.

Data the new Oil

Any analysis team would work day and night to justify the reason for their being. There are enough articles being shared on the internet on arriving at a Return on Investment for Analytics (RoIA). However, the main service that any of these teams did was to crunch business data into A-has. This hasn’t changed over the years, and a lot of analysts derive job satisfaction through this very hunt for the A-ha! from their audiences.

The switch to being a core business

Data and business analysis was until now a support function, which needed business data in order to thrive and be effective. Aside from very few models (those that sold business critical data such as ratings, organizational data, etc), the data was never used as the primary product.

There was always a pre-activity and an analysis activity for that data to be useful. However, over the years I am seeing that has changed. Data is now being presented and sold as the main product.

Data as the product

Those of you who know Bloomberg, Hoovers, S&P or CRISIL, would know that data as a product business model works. Now that you know the pattern, let’s take a look at how this business model works.

Data collection as a ancilliary service

There is one function of the business which works with the entire industry it is catering to, to collect data. This more often than not is made available as a freemium or free service.

Some examples of this would be – Alexa Certified metrics, Google Analytics, Walnut app, Swaggerhub, etc.

You get the general idea here. If a good product or service is offering you a free plan, more often than not the data you are entering on that platform would be mused for multiple usecases. Not just for your primary use case.

Data aggregation and visualization

This is akin to the marketing function, and most probably gets a lot of early adopters talking good things about the product.

E.g a blogger singing paeans about Google Analytics, an industry benchmark visualization being shared, data report about a competitor, etc.

This way, the inherent value in the data is presented.

Data access and pricing plans

This is how the business is monetizing the data. By selling access to it. Often on a pay per use basis, or a per data point basis. Note, there might be multiple reports given to the user, however the user has to do the analysis on their own.

E.g SEMRush, SimilarWeb, Alexa, etc.

Wait, these are all old products

Yes. They have been around for quite some time. However, I am seeing that other industry are also copying this model. I recently spoke to someone in the pharma industry who was selling aggregated prescription data to pharma companies.

The credit industry has already been doing this for so many years. TransUnion is a perfect example. In India, most working professionals are familiary with their CIBIL scores. What few people realize that CIBIL is a TransUnion company. Similarily, CRIF score (which is an alternative bureau) belongs to Experian.

What gets my goat in this scenario, is that the firm which is collecting data is based out of another country! This firm now claims to own and know the data of citizens belonging to another country.

Shut up and take my data

Let’s go back 300 years or so. The British killed the Indian textile industry by mutilating the weavers who used to make cloth. Then they bought the cotton and other crops at throwaway prices, that cotton is similar to the data that is being collected. The industry grade cotton which was then imported back in India is similar to the data aggregation and reports that are being sold.

The only difference is that 300 years back, we were scared of the East India Company. This time around, we are welcoming the data traders with open arms. Should we not be a bit more aware of who and how our data is being used?

The reason why EU is taking such a harsh stance with GDPR is a bit more clear. Where is the call for privacy and better data sharing protocols?

🎯 Why You Need to Stop Tracking These 5 Metrics

This article was written as part of the SEMrush Big Blogging Contest.

One of the things that going digital does to any brand, is that it suddenly gives access to a lot of data. Data, that opens up a world of possibilities.

Possibilities which had not earlier been anticipated or even thought of. Somehow, it propels teams to start thinking in terms of achieving certain data metrics … and that seems to justify the sheer obsession with data.

Read more🎯 Why You Need to Stop Tracking These 5 Metrics

AMP and Advertising

Mobile Content

This blog is a modest small-tier blog. It does not get too much traffic (much to my chagrin) and therefore expecting the blog to monetize is too much. However, I have steadily written my thoughts and opinions on this … for the past 7-8 years now.

Looking at such a long time range allows me to study how blogging and blog monhersetization has changed over the years. Especially now with mobile form factors being the main devices that users tend to consume content with.

Read moreAMP and Advertising

Marketing for India2

As someone who has been in the area of Digital marketing for the past few years (close to a decade now), it’s interesting to note and see how it has evolved. Right from the open market economics that AdWords grew upon to the game theory dynamics of Search Engine Optimisation, the way the entire industry has been changing is fascinating.

This article on English Tax and building for the next billion Indian users by Sajith Pai makes you stop and think. At this point, all the marketers and brands are busy selling to that sliver of audience who are online and are english speaking, affluent, willing to whip out their credit cards and make a purchase.

The next Billion

However, there is a larger audience out here, 10 times as much. A billion people, who may not be comfortable with English, who may not have approved credit cards and credit lines … but who are online.

Thanks to the launch of Jio, you now have an audience who may not be affluent, but who are there online. The same audience is being targeted by brands in a language that is not native to them.

English Tax

What is the English Tax? It’s the overhead that a user has to go over to understand what is being said. English is not my mother tongue, however after just under 4 decades of being subjected to both formal and informal education, I have started to think of English as my primary language.

However, that may not be the case of the next Billion. They may not even understand English, and thanks to Google or Apple, they would still be able to browse the web online without even typing a single English letter!

To top it all off, this audience is not being targeted online, not because they do not have a foot print, but because they do not understand the language in which they are being targeted.

This is bad.

Not only would they need re-phrasing of communications, but also a lot of mis-selling and mis-communications would be currently done to them.

Responsibility in Media

Yeah, this section is a joke! However, as digital platforms evolve, can the major players like GAFA take a much more responsible stand on exposing the India2 to the internet?

It’s not as if something is wrong with them. Please note, I am not saying that. However the internet which is most relevant for India2 is in the making and a lot of players are just ignoring this huge blue ocean that needs to be made.

There are content oriented players like BhaDiPa (Bharatiya Digital Party) and  TVF (The Viral Fever) who are making content in regional languages, pretty sure there are many more as well. However, one look at the keyword search volumes in Hindi and Marathi, and I know that we have still miles to go.

This audience for instance may not be doing a lot of searches, however, they definitely are there on Facebook, on WhatsApp, etc.

What can we do to engage as brands and marketers with this audience?

Going Regional

One step is always to speak the same language. I always loved the devnagri script, it just looks graceful when in comparison to the English script. Call me biased. However, as a marketer I would love to see some really good creatives, copy and content being pushed out there in regional formats.

I have seen this being done by some organisations, and just going by their data consumption numbers makes one re-think the language in which they are publishing! Similarly, the concepts of marketing wont change, but since the language is changing, so would therefore the format and forms. Just taking a Facebook update and translating it to Marathi won’t do. It has to be not just re-phrased but even re-thought … some of the memes and mental models that one language/culture has may pretty much ensure that the whole line of messaging be irrelevant.

I think as an industry based in a country that’s slowly emerging online, we are barely scratching the surface on these things.

A relic in a new age

Another day, another James Bond rumour. Of all the great franchises out there, 007’s—perhaps appropriately—seems to play its cards the closest to its chest. Eon Productions always rations information about where their legendary character is going right up to the point they are ready to announce his destination, and for what looks to be Daniel […]

via What if killing off Daniel Craig’s James Bond makes sense? —

I love Bond flicks. As someone who has watched James Bond escape traps and defeat villains right from childhood days, it’s a treat to read this article.

Not only does the author know his Bond, but also he is able to tell apart the different Bonds from each other (Connery from Moore, Brosnan from Craig, etc). However, do read through the entire article that I have linked above. Perhaps, it is time for Mr. Bond to die.

What the author seems to suggest is that Bond being the immortal he is manages to still beat the odds, but is feeling the pressures of age. James Bond is a legacy system.

What is a legacy system?

In organizations, a legacy system is that system which has been running for quite some time. It is running because the organization does not feel the need to update the system and the system has been running satisfactorily.

By this I mean, the system has its fair share of problems, but its a known devil. People know the workarounds, they know how to work with the system and how to sometimes work around it. They live with it … but every year they do a calculation of what will it take to replace it. Since what the system does represent is technical debt.

Unless the system does not magically upgrade itself or reinvent itself, the technical debt would be carried over.

What can be done to technical debt?

It has to be paid back in full, and sometimes with interest

This debt has to be paid either in terms of loss in productivity or in terms of cost incurred in upgrading the system.

So, either you keep updating and patching the legacy system … so in Mr. Bond’s case, there’s a constant need to evolve and keep getting better.

Or you simply retire the system, or replace the system with a slightly modern version of the sytem. What we have been seeing when it comes to the casting of James Bond. Daniel Craig would now shoot his 5th Bond flick. This would be his last.

What do you want for Bond?

Being an ardent James Bond fan, I would love to see Bond re-invent himself into a mix of Q and M who is also on the field. If wishes could be horses, beggars would ride.