From 1926cbcb0cc9a7b8efb5d60f3910e3e6bc491eb9 Mon Sep 17 00:00:00 2001 From: Dominik Wilkowski Date: Fri, 13 Aug 2021 11:54:24 +1000 Subject: [PATCH 1/2] Added RFC for docs site improvements --- RFCs/1-approved/docs-site.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 RFCs/1-approved/docs-site.md diff --git a/RFCs/1-approved/docs-site.md b/RFCs/1-approved/docs-site.md new file mode 100644 index 0000000..580f396 --- /dev/null +++ b/RFCs/1-approved/docs-site.md @@ -0,0 +1,24 @@ +--- +Status: `Proposal` # Please do not change this. +Implementer: # It will be changed upon merging and as it moves through the RFC stages +--- + +# Build a simpler docs site + +## The issue to be solved + +The current docs site, while static and well designed, is outdated and not driven with the same pace as the components. +Co-location of docs and components will also solve the issue of features that are being developed having to include docs (changes) in the same piece of work making the definition of done more transparent. +We need to retain the static nature of the docs site so we can continue to rely on free static hosting like GitHub pages or Netlify etc. +the information of the pages are also outdated not that the components have moved into the Design System Au group. + +## A short description of the solution + +We should co-locate the docs site into the same repo as the components and drive the documentation of each component from a docs file that sites in the same folder as the component itself. Preferably a README.md file that can be digested by the docs site. +We should strip other irrelevant pages from the site as well and perhaps add pages describing this groups efforts. + +## Technical details + +Prior art here: https://github.com/dominikwilkowski/ds-workshop + +MORE DETAILS COMING 😬 From 36b58bca2c85ef34a1a06f9563a80c141f94329d Mon Sep 17 00:00:00 2001 From: Dominik Wilkowski Date: Tue, 14 Dec 2021 14:29:14 +1100 Subject: [PATCH 2/2] finished RFC --- RFC-by-stage/1-approved/docs-site.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/RFC-by-stage/1-approved/docs-site.md b/RFC-by-stage/1-approved/docs-site.md index abb157f..2d2e467 100644 --- a/RFC-by-stage/1-approved/docs-site.md +++ b/RFC-by-stage/1-approved/docs-site.md @@ -20,6 +20,10 @@ We should strip other irrelevant pages from the site as well and perhaps add pag ## Technical details -Prior art here: https://github.com/dominikwilkowski/ds-workshop +Implementation: https://github.com/dominikwilkowski/ds-workshop -MORE DETAILS COMING 😬 +The docs site will be inside the monorepo so we will be able to re-use the docs for each component from each component folder. +The design will simplify a bit to keep it simple. +I propose [next.js](https://nextjs.org/) to build the site off of it's own react components. +We will then use the [`export`](https://nextjs.org/docs/advanced-features/static-html-export) task of next to generate flat static html pages. +That way the page will work without js.