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
Was this helpful?
4 min read
Last updated
Was this helpful?
Whenever you hop into any under , you'll spot the same pattern in the , resembling something like this:
Adopting this approach comes with its mix of pros and cons, but I'm inclined to argue the scale tips more towards the positives.
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.
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.
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.
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.
Rather than stuffing the heading and contribution links directly into README.md / , you'll find them on GitBook, our platform of choice.
Documentation 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 .
GitBook does provide a GitHub syncing feature, offering a glimpse into what the hideout repo might look like . Honestly, while placing SPoF with a third-party isn't ideal, alternative communication channels like and make this concern less daunting.
Plus, GitBook runs on , so any potential outages should be swiftly handled.
GitHub's markdown support and wiki functionality are too basic and frankly, more trouble than they're worth. On top of that, .
Though exile.watch docs mainly use integration, the sheer ease of embedding various blocks with a simple slash command is a clear win.
Plus, outdoes by miles.
You heard that right. While it may seem counterintuitive for an open-source project, limiting README contributions helps sidestep meaningless spam.
For more context, check out .
Author: About exile.watch: Github: Visit to experience it first hand
