Why project's local setup instructions are not part of README?
4 min read
PreviousThe savior amidst the chaos of dependency updates - DependabotNextLeveraging Lefthook to enforce commit guidelines at exile.watch
Last updated
4 min read
Last updated
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.
Adopting this approach comes with its mix of pros and cons, but I'm inclined to argue the scale tips more towards the positives.
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.
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.
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.
In the realm of Open Source, having everything in one spot is a game-changer. Enough said.
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.
Yes, GitHub offers similar functionality, but GitBook makes accessing drafts and seeing changes as easy as a few clicks—no terminal commands necessary.
GitBook surpasses GitHub wiki in creating organized categories and subpages, enhancing the overall reading and navigation experience.
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.
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
