This project is used to generate the Data Platform Documentation Site.
You can edit the pages files directly in this project, which are formatted as .md files and once committed the changes will become visible on the site.
The site is broken down into two sections:
- Data Dictionary
- The Data Dictionary contains definitions of Data Entities
- Playbook
- The Playbook contains articles on the processes involved in using the Data Platform
- Architecture Decision Records
- Records of architecture decisions made regarding the platform. See Architecture Decision Records (ADRs) below.
- Technical Spikes (Discovery)
- Records of findings around technical investigations concluding in an Architecture Decision Record (ADR).
The Data Platform uses Architecture Decision Records (ADRs) to document architecture decisions that have been made.
They can be found in pages/architecture-decisions
and contributed to with
adr-tools.
Note: A custom template is provided in this project user pages/architecture-decisions/templates/template.md
, this is
automatically picked up by adr-tools.
This website is built using Docusaurus 2, a modern static website generator.
yarn install
If you don't have yarn
installed, do so by running:
npm install --global yarn
yarn start
This command starts a local development server which you can view at http://localhost:3000/Data-Platform-Playbook/. Most changes are reflected live without having to restart the server.
yarn build
This command generates static content into the build
directory and can be served using any static contents hosting service.
You should open a pull request with your suggested edits, and seek approval from another developer on your changes. New pull request notifications are automatically sent to the #data-platform-chatops
Slack channel.
When changes are merged into the main
branch, they will be automatically deployed to the Data Platform Documentation Site via GitHub actions.
To deploy manually you can run:
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages
branch.