A woman using her laptop in a public space, facing tall glass windows
Photo by Bonnie Kittle on Unsplash

I started Freelancing In India: A Handbook a lit­tle over two years ago, cov­er­ing much of my prior ex­pe­ri­ence in the first six months of cre­at­ing the repo. It was just a sim­ple README.md file view­able on GitHub.

Over time, it gained a small but re­spectable num­ber of stargaz­ers. Seeing this, I de­cided it was time to move it to some­thing more struc­tured and more eas­ily view­able.

I also wanted to ex­pand the scope of the pro­ject from just work­ing with in­ter­na­tional clients to SaaS of­fer­ings, paid ap­pli­ca­tions on app stores, work­ing with do­mes­tic clients, and so on.

I don’t have much first-hand in­for­ma­tion on these as­pects, but I’m count­ing on the few re­sources I’ve found on­line to make for a suf­fi­cient start­ing point and the com­mu­nity to step in!

VuePress

I de­cided to use VuePress for its promise of sim­plic­ity. I got started in about a cou­ple of hours, with very lit­tle frame­work fight­ing to do. It al­most just worked. Had I had prior ex­pe­ri­ence with it, I doubt I would have spent even as much time as I did.

The de­fault theme is great, and even comes with these lit­tle bal­loon-style con­tain­ers for tips, warn­ings, dan­ger, and more. Here’s an ex­am­ple of a warn­ing from the site it­self:

A warning as seen on the documentation

It also in­cludes a very easy to use search bar, a home page tem­plate, and the abil­ity to add to nav­i­ga­tion. Although not vis­i­ble in the screen­shot be­low, it also has a last up­dated time­stamp for every page to re­flect on the re­cency of the in­for­ma­tion. It’s also fully re­spon­sive! Being server-side gen­er­ated, we ab­solutely don’t lose out on SEO. 😁

A full screenshot of the documentation, with a sidebar navigation and a search bar with the input "import" and its search results

My only gripe?

I wish there was an op­tion to gen­er­ate the side­bar links au­to­mat­i­cally. At the mo­ment, you need to spec­ify it man­u­ally in the con­fig­u­ra­tion file, like so:

// .vuepress/config.js
sidebar: [
"/docs/",
"/docs/getting-started",
"/docs/defining-export",
"/docs/getting-paid",
"/docs/gst-returns",
"/docs/income-tax"
],

Of course, the con­trol and flex­i­bil­ity is great. Still, a con­fig­u­ra­tion op­tion to let VuePress parse the di­rec­tory and build the tree on its own would have been amaz­ing. In sce­nar­ios where we wish to in­clude every­thing, it would be very handy.

However, spec­i­fy­ing the side­bar nav­i­ga­tion is a mat­ter of five to ten min­utes at most. It is far from a deal breaker.

Final take

With all the boil­er­plate taken care of, VuePress was re­ally en­joy­able to set up and I will def­i­nitely con­sider it again for any kind of doc­u­men­ta­tion. It claims to be geared more to­wards tech­ni­cal docs, but worked just as well for my hand­book.

Now it’s time for me to find con­trib­u­tors. 🙂