[ADR-0001] Use Gitbook for Technical Documentation
Decided to move to Gitbook all Technical documentation (Development & Infrastructure)
Last updated
Decided to move to Gitbook all Technical documentation (Development & Infrastructure)
Last updated
Status: accepted
Deciders: Engineering Team
Currently Technical Documentation lives in the Handbook, with an and everything else organized under the . On the other hand Gitbook is a platform specifically for maintaining documentation, based on Markdown. We created a in GP Gitbook account to test how a potential structure of our documentation would look.
Community Management Team should be consulted, since this affects the internal development community too.
Move to Gitbook
Stay in the Handbook
Chosen option: Decided to move to Gitbook all Technical documentation (Development & Infrastructure)
Good, because Gitbook is meant to be used as a documentation platform providing better UI/UX for that task.
Good, because docs can be grouped in categories, or browsed as a series of a guide, creating a user journey.
Good, because it’s connected and synced with a public Github repo, so it’s easy for an external contributor to update the documentation by opening a Pull Request.
Good, because the documentation on the repo is just Markdown so we are not locked into Gitbook, if we ever choose to leave.
Good, because it’s the choice of in the Org (eg. Global Support), so people can discover it easier but they are also used to it.
Good, because everything regarding P4 is in one place.
Bad, because the perception is that the Handbook is for internal audience. That’s not always the case for the technical documentation.
Bad, because we sometimes need to do custom development just for the Handbook.
Bad, because it demands manual styling customization for technical documentation (e.g scripts/coding pieces) or instructions.