Why project's local setup instructions are not part of README?
4 min read
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:
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
Last updated
Was this helpful?