Why project's local setup instructions are not part of README?

4 min read

exile.watch logo

Whenever you hop into any project under exile.watch's GitHub profile, you'll spot the same pattern in the README.md file, resembling something like this:

exile.watch README.md

Rather than stuffing the heading and contribution links directly into README.md / CONTRIBUTION.md, you'll find them on GitBook, our platform of choice.

This is intentional

Adopting this approach comes with its mix of pros and cons, but I'm inclined to argue the scale tips more towards the positives.

Let's start with the bad first

Single point of failure (SPoF)

Documentation SPoF (single point of failure) is now part of 3rd party provider which is GitBook. If GitBook goes down, so does exile.watch documentation and local setup instructions.

GitBook offers a syncing functionality with GitHub and you can check how hideout repo could look like at https://github.com/exile-watch/hideout/tree/0330ad9b5392650b96ec2ca8f233cac0ce3fda59.

GitBook does provide a GitHub syncing feature, offering a glimpse into what the hideout repo might look like here. Honestly, while placing SPoF with a third-party isn't ideal, alternative communication channels like GitHub's discussions and Discord make this concern less daunting.

Plus, GitBook runs on Cloudflare, so any potential outages should be swiftly handled.

Unintuitive and potentially annoying at the beginning

Typically, diving into a new company or open-source project, README.md and CONTRIBUTING.md are your go-tos. This is standard for most projects.

However, needing an extra click to access this information can be irksome, despite not being a deal-breaker given the benefits you'll soon discover.

But what about GitHub's wiki? It's been built for this exact reason!

No. Full stop.

GitHub's markdown support and wiki functionality are too basic and frankly, more trouble than they're worth. On top of that, there are no plans to add more features anytime soon.

GitBook, in contrast, excels in user-friendliness and functionality.

The good

Centralized documentation

In the realm of Open Source, having everything in one spot is a game-changer. Enough said.

Plenty of integrations

Though exile.watch docs mainly use Lucid.app integration, the sheer ease of embedding various blocks with a simple slash command is a clear win.

Plus, GitBook's hint system outdoes GitHub's alert feature by miles.

Easily accessible drafts with diff changes

Yes, GitHub offers similar functionality, but GitBook makes accessing drafts and seeing changes as easy as a few clicks—no terminal commands necessary.

Page / book flow

GitBook surpasses GitHub wiki in creating organized categories and subpages, enhancing the overall reading and navigation experience.

Limited README Exploitation for Hacktoberfest

You heard that right. While it may seem counterintuitive for an open-source project, limiting README contributions helps sidestep meaningless Hacktoberfest spam.

For more context, check out this video.

Conclusion

To wrap it up, shifting to centralized documentation via GitBook is primarily about streamlining information access and safeguarding against low-effort Hacktoberfest contributions.

It's a strategic choice that, while not without its downsides, offers significant benefits in the grand scheme.

---

Author: Sebastian Krzyżanowski About exile.watch: https://docs.exile.watch/ Github: https://github.com/exile-watch Visit https://exile.watch/ to experience it first hand