--- tags: meta title: Why Gitbook? description: We recently moved from a git-based workflow to Gitbook. What did we gain out of that? --- # Why Gitbook? We've recently moved away from our github pages to Gitbook domain. This document tries to capture the upside and potential concerns of this move. --- ### Upsides - _Go Live_ time is near zero Once the content is ready, we can go live in matter of seconds. This cuts down the loop, and empowers us to iterate faster. Earlier, we had to get a merge / pull-request review dance done; then a Github action build which would eventually update the site with new content. Aside from common issues around maintaining and updating a CI pipeline (writing code isn't the hard part, maintaining it is); we had limited resources available in the form of monthly limit on free minutes in Github actions. With Gitbook, these procesesses are not our concerns anymore. - _WYSIWYG_ editor Our present focus is to get enough quality content into the wiki. An editor like Gitbook's help with that. Maintaining our website would have meant figuring out this processes - _how would a contribution look like once it goes live?_ There's immense value in seeing that from the beginning, and not have to wait for a Netlify deployment for that - Media hosting Building our own website would mean at the very least, we'd need a way to host images. We'd also need options to process the image through a media pipelines, to generate & serve right image specific to device, or worry about bandwidth charges etc. It'd be even harder to build a good image viewing experience. Media experience on Gitbook is decent, and media hosting is a solved problem. It also keeps backup media assets in `.gitbook/assets` directory. - Search & Analytics Gitbook content-wide search is pretty robust, orders content as per relevance quite well. Since we were turned down by Algolia, setting up our own Typeahead would've been like re-inventing the wheel. We have not enabled GA, because we'd rather focus on the ratings widget's results. But we have that option. - Fancy UI elements That we don't have to build on our own, comes out-of-box. Overall, Gitbook gives us the perfect recipe for _move fast, and don't break things_. It helps us _ship content_ with geat UX :tada: :tada: --- ### Concerns Not all is rosy in Gitbook land. We've faced multiple issues that's detrimental to our workflow - Privacy Gitbook fetches main email ID from Github account, and pushes content to Github using that as git email ID. This has the potential to expose someone's personal email ID on the public internet. Luckily, most of us have Github account tied to throwaway emails, that we don't mind it getting doxxed. However, Gitbook should provide an option to change / use Github-provided throwaway no-reply email ID to push content on Github. We have to keep this in mind when someone joins the Gitbook org. - Non-standard Markdown Gitbook has created custom Markdown parsers, that's not compliant with standard markdown formatter / parsers. This means a potential vendor lock-in, if we ever were to move to our own hosting solution in future. - Save loop Gitbook uses Firebase under the hood, and trying to save content of drrafts throws 503 repeatedly. The fact that a retry logic was added, shows people within Gitbook are aware of this issue, just not sure how to go about solving it. We discovered that using a VPN solves this problem. Apparently region-specific problem, with Firebase / GCP. - Comments / Feedbacks Earlier, with HackMD, we were able to get review comments from people who're not part of HackMD org. This was valuable. Now, we are allowed to get comments from only the writers in Gitbook org. Given it's too easy to push live changes on Gitbook site, we had to restrict whom we can add as writer in Gitbook org. --- ### Parting Thoughts - On the privacy part, We've initiated a dialogue with Gitbook support team. Let's see if they at least manually update our email IDs in the backend. We'd be careful with whom we add in our Gitbook org, and how to onboard them. We're also trying to update the email addresses in git history (though it's not as effective, since it's already out in the public). - We had faced similar issue with markdown in Discord embed earlier. We have to write some parser that normalizes between these two. But more importantly, we have to actively work towards avoiding a vendor lock-in. :bulb: **Proposal**: In addition to creating series / chapters on Gitbook, we also publish on HackMD as book, for each of the chapters. This would verify that we have utilities in place to standardize the markdown on demand, pushed by Gitbook bot. Our HackMD content can be a bit outdated; but we can automate this as well. Say, it syncs once a week. We can even offer it as backup mode of reading, and de-risk ourselves. - VPN-based saving is ok for now. Hopefully this issue gets resolved this week. - We can tune our workflow like this to work around this problem - create content on HackMD, share for inline comments as feedbacks. Fix them on HackMD. Then go to view mode (do NOT copy from edit mode), copy paste content into Gitbook. It works even with media (images / videos) in the page. Basically, use Gitbook only as the final step in the process, or add small updates in place. Or to validate how some changes would look like. While do most of the content development work outside of Gitbook.