> For the complete documentation index, see [llms.txt](https://engineering.exile.watch/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.exile.watch/march-2024/why-projects-local-setup-instructions-are-not-part-of-readme.md).
# Why project's local setup instructions are not part of README?
exile.watch logo
Whenever you hop into any [project](https://docs.exile.watch/projects/hideout#links-to-projects) under [exile.watch's GitHub profile](https://github.com/exile-watch), you'll spot the same pattern in the [README.md file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes), resembling something like this:
exile.watch README.md
Rather than stuffing the heading and contribution links directly into README.md / [`CONTRIBUTION.md`](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors), 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)](https://en.wikipedia.org/wiki/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 .
GitBook does provide a GitHub syncing feature, offering a glimpse into what the hideout repo might look like [here](https://github.com/exile-watch/hideout/tree/0330ad9b5392650b96ec2ca8f233cac0ce3fda59). Honestly, while placing SPoF with a third-party isn't ideal, alternative communication channels like [GitHub's discussions](https://github.com/exile-watch/hideout/discussions) and [Discord](https://discord.gg/UUquE4uv7k) make this concern less daunting.
Plus, GitBook runs on [Cloudflare](https://www.cloudflare.com/), 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](https://github.com/orgs/community/discussions/23914#discussioncomment-3242152).
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](https://lucid.app/) integration, the sheer ease of embedding various blocks with a simple slash command is a clear win.
Plus, [GitBook's hint system](https://docs.gitbook.com/content-editor/blocks/hint) outdoes [GitHub's alert feature](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) 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](https://hacktoberfest.com/participation/) spam.
For more context, check out [this video](https://www.youtube.com/watch?v=5nY_cy8zcO4).
## 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](https://github.com/sbsrnt)\
About *exile.watch*: \
Github: \
\
Visit to experience it first hand