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.

A fortress of regulations

For the past 6 months or so, I have been involved in building up a fintech based business. You might have seen me post about real estate and how the young Indian workforce needs help to own a house. This organization is HomeCapital which provides home down payment assistance for first time home buyers. In fact, it’s India’s first home down payment program.

The product itself is pretty unique and involves a bit of financial engineering. It’s an unsecured personal loan made available to the home buyer at 0% interest. To know more feel free to drop by our office for a chat and a cuppa!

Business traction and growth

The business is doing well and therefore it has quickly attracted a good set of investors. As we are gearing up for a Series A run, one of the question that I am increasingly seeing in conversations is this –

What technology barriers to entry does your business have?

The first time I heard this question, I was stumped. It’s not as if the core product was a technology driven product. Given enough time and money, any competent person should be able to build any of the following systems –

  • Loan origination
  • Application management
  • Loan management
  • Customer Relationship Management

These are business support systems, and they will never be a technology differentiator. The simple reason being that there are too many service providers and SaaS products out there which provide alternatives for them.

Yes, I could always claim a better UX, a robust and secure system. However, these are fast becoming hygiene factors and thanks to cloud based solutions fast becoming a commodity.

How does this impact a relatively new industry?

Read on. It’s a good case of how the mayor of Paris has decided to take matters in her hands in order to stop an overcrowding of a young industry.

There are a dozen electric scooter companies operating in Paris right now. There are so many that the Mayor just announced that she will reduce that number to three with new rules for electric scooters in Paris.

via Low (No) Barriers To Entry — AVC

Artificial barriers are being constructed in order for three of the businesses to be sustainable. The young electric scooter industry is being protected in this case by Paris.

Very similar to this, the FinTech industry in India is relatively young, and the Government of India has taken an active interest in this. One of the instances where the banking and lending industry in India was protected was where RBI drastically changed the P2P startup landscape by limiting individual investors to 10 Lakh INR.

Most developing countries are taking this approach for multiple industries. A wait and watch approach with a beady eye on the innovations and changes ensures that most policies that are being passed are in situ with the economic environment.

Protecting lush markets

What the mayor has beautifully done is protect the largest european market of electric scooters. One reason for more than a dozen startups to spring up in this market was that it was fairly easy for someone to join a business, learn the ropes and then start on their own. However, what will happen if one of these fly by night operations were to suddenly go down under? Suddenly the entire market starts stumbling. Would you as a governing body allow this to happen?

No. I would rather have 3-4 stable operators providing this service as opposed to 12-15 firms. It’s regulation, yes. It’s against the natural laws of economy, yes. However, it is being done to protect the market. Over a period of time this triopoly will try creating a seller’s economy, however the regulation will ensure that no one player can generate super normal profits. This creates a pretty strong barrier. An impregnable fortress of regulations that cannot be overcome.

India and FinTech

If you now look at the FinTech industry in India, then there are many regulations. This is not so much a concern as much as the fact that these regulations keep evolving as the industry evolves.

Take the fact that since September 2018 the Aadhar based KYC norms have come to a standstill. It is only last week that the RBI has allowed for e-KYC to be re-initiated. Now through in a recent trend such as DeepFake in their, and now you have regulators in a dizzy. What the major players in banking and lending are doing is looking up to the regulator to take decisions … these decisons are being taken over a long period of time (approximately 6 months in the case of e-KYC).

That’s two business cycles. Enough time for an upstart to start-up. India is a lare country and we haven’t really started making fintech products for the 66% of the non-english speaking Indians. There is hope of growth there, and hence the regulation barriers will be slowly built in that area.

Is a barrier needed?

A barrier to entry is needed when the market becomes small and the players have to compete for transactions. However, what is unique about billion people economies such as India and China is that the sheer volume of users is so high that there is always room for more.

Even in such a space where every month there is a new lender or two cropping up, the Indian real estate and lending space still remains under utilized. Housing for all still remains a distinct dream, and until then, instead of building barriers, perhaps we might want to think about building bridges.

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!

 

A female Stanford labor economist urges graduates to avoid the trap of “trying to have it all” — Quartz

Graduation speeches are usually brimming with optimism and idealism. Be your best self. Lean in. Make your dream work. Myra Stober, a labor economist and professor emerita of education at Stanford University, took a different tack, offering Stanford’s graduate school of education students hard truths and pragmatic strategies for managing work-life balance. “You can harmonize…

via A female Stanford labor economist urges graduates to avoid the trap of “trying to have it all” — Quartz

Finally a person who sees things the way I do.

Work and Family are two institutions which require a full time commitment. Having a balanced way of life doesn’t really help maximize on either of the two fronts. Unless, your significant other and you work towards fulfilling each others’ career goals.

 

Taking a look at Jetpack Stats

Let me state upfront that I love Google Analytics. I use it at work in 13 Llama Interactive to measure the effectiveness of the campaigns that my team runs.

That being said, I will try and not be too biased about comparing Jetpack Stats to Google Analytics. As a marketer, the way I look at an analytics package is from an ability to extract a fair amount of data.

However, Jetpack Stats is on top of WordPress and available to all WordPress based sites which are connected to the WordPress.com site. This makes Jetpack Stats primary user base as bloggers.

Let’s see what Jetpack Stats has to offer.

The wp-admin Dashboard Integration

Jetpack Stats puts a nice pretty looking graph on the wp-admin Dashboard. This is how it looks like for my site –

Jetpack-Stats-on-wp-admin-Dashboard

Now, this is fairly similar to the Audience Overview you get when you check out Google Analytics.

Google-Analytics-Dashboard

Straight off the bat, I prefer Jetpack Stats overview as opposed to the one given by Google Analytics. Jetpack Stats also provides me with how my posts have performed this day, this report would be available in GA witin the Behavior section, the Site Content report.

The Top Searches that you see in the screenshot would have been helpful had it been accurate. Unfortunately, Google accounts for the majority of organic traffic on my site, and most of that traffic is encrypted. Thus, these keywords that you see (really, I rank for ‘big ass girl dunes’) are not a complete set!

Jetpack Stats does not talk to Google Webmaster Tools, which now is the only source of this keyword data.

Jetpack Stats Posting Activity

One awesome feature about Jetpack Stats is the posting activity screen –

Jetpack-Posting_Activity

This data is shown with a correlation of average traffic per day as well as traffic per month. You could always get this data in Google Analytics (here is a useful post I had written some time back – Google Analytics for Content Marketers).

It’s just this kind of insights that makes me keep Jetpack around for my measurement requirements.

Jetpack Stats vs Google Analytics

Jetpack Stats is a very lightweight tool and it would be useful for a simple blog. However the minute we enter the realm of finding user engagement and performance marketing, Jetpack simply does not have those features yet.

This is where Google Analytics shines through with its Event tracking.

Having said that, Jetpack Stats is an apt solution for a user who is more focused on the publishing process.

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