From 3152572a36e4313bd89358b766707d0aa2a37878 Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Wed, 31 Aug 2022 08:36:38 -0700 Subject: [PATCH 01/11] Create RFC-015-Chronologue.md --- RFC-015-Chronologue.md | 91 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 RFC-015-Chronologue.md diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md new file mode 100644 index 0000000..3cf9f9f --- /dev/null +++ b/RFC-015-Chronologue.md @@ -0,0 +1,91 @@ +{ +- Use this template when submitting a request for comment (RFC) proposal to the Good Docs Project. +- See the [README](README.md) for more information about the process. +} + +# Title of your proposal + +## Proposed by + +{Put your name and/or your Slack handle here.} + +## Current status + +See the status indicated on the pull request description. + + +## Proposal overview + +{Summarize your proposal in this section in about 1-2 paragraphs.} + + +## Motivation + +{What problem does this proposal try to solve?} + + +## Proposal + +{Explain the proposal in more depth here and make your best argument for its adoption.} + + +## Consequences + +{Explain what impact this proposal will have on the community, both positive and negative.} + + +## Links and prior art + +{This section is optional if you want to [link](https://example.com) to other resources.} + + +## Open questions + +{This section is optional and is where you can list questions that won't be resolved by this RFC, including those raised in comments from community members.} + + +## Decisions deferred + +{This section is option and is where you can list decisions that won't be resolved by this RFC, but which should be raised at a later time.} + + +## Feedback + +{If you accept feedback from a community member, you will incorporate it into your RFC before it is accepted. +If you reject feedback, note that rejected feedback here before resolving the conversation.} + + +## Implementation checklist + +If this proposal is accepted, the following tasks must be completed: + +- [ ] Task number one +- [ ] Task number two +- [ ] Task number three, etc. + + +## Votes + +Votes as per our [decision process](https://thegooddocsproject.dev/decisions/): + +Project steering committee (listed alphabetically by first name): + +- Aaron Peters: +- Alyssa Rock: +- Ankita Tripathi: +- Bryan Klein: +- Cameron Shorter: +- Carrie Crowe: +- Erin McKean: +- Deanna Thompson: +- Felicity Brand: +- Gayathri Krishnaswamy: +- Morgan Craft: +- Nelson Guya: +- Ryan Macklin: +- Tina Lüdtke: + + +Community members who voted (non-binding): + +- {Your name}: {Your vote} From 8e4a1ffe605478517239dbd4d4003e72edd9a99b Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Wed, 31 Aug 2022 08:53:14 -0700 Subject: [PATCH 02/11] Add Document structure --- RFC-015-Chronologue.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index 3cf9f9f..4ec41d8 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -1,33 +1,39 @@ -{ -- Use this template when submitting a request for comment (RFC) proposal to the Good Docs Project. -- See the [README](README.md) for more information about the process. -} - -# Title of your proposal +# Chronologue processes and tools ## Proposed by -{Put your name and/or your Slack handle here.} +[Tina Luedtke](https://thegooddocs.slack.com/team/U02EQQDFLE8) ## Current status -See the status indicated on the pull request description. +Draft ## Proposal overview -{Summarize your proposal in this section in about 1-2 paragraphs.} +This proposal outlines the responsibilities, ambitions, needs, and ways of working within the Chronologue working group and how we interact with the Template working group. Specifically, the proposal discusses: +- [Function of the Chronologue project](#function) +- [Role Matrix](#roles) +- [Writing process](#process) +- [Mock product: Technical and creative needs and a proposal for tooling](#tools) -## Motivation -{What problem does this proposal try to solve?} +## Motivation + +This proposal aims to solidify our past decisions into a formal foundation from which the group can evolve and grow from. +More specifically, the proposal highlights the role of the Chronologue working group within the Good Docs project, how we work, and what tools we use. ## Proposal -{Explain the proposal in more depth here and make your best argument for its adoption.} +### Function of the Chronologue project +### Role Matrix + +### Writing process + +### Mock product: Technical and creative needs and a proposal for tooling ## Consequences @@ -48,6 +54,8 @@ See the status indicated on the pull request description. {This section is option and is where you can list decisions that won't be resolved by this RFC, but which should be raised at a later time.} +- Feedback channel for content (Reason: This should be unified across the sites we maintain?) + ## Feedback From 9a6b147e1d4b9fd0a489550e1945a5b5cc479756 Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Tue, 6 Sep 2022 14:42:24 -0700 Subject: [PATCH 03/11] Update RFC-015-Chronologue.md --- RFC-015-Chronologue.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index 4ec41d8..7cc8323 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -6,7 +6,14 @@ ## Current status -Draft +- [x] Draft +- [ ] Under discussion +- [ ] Final comment and voting (until YYYY-MM-DD) {{Add date after selecting this status.}} +- [ ] Accepted +- [ ] Rejected +- [ ] Implemented +- [ ] Deferred +- [ ] Withdrawn ## Proposal overview From 1e39252662deb8006bb6f7991c0a91406c22092f Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Thu, 8 Sep 2022 07:30:18 -0700 Subject: [PATCH 04/11] Add Function description --- RFC-015-Chronologue.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index 7cc8323..fcc35f7 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -36,6 +36,20 @@ More specifically, the proposal highlights the role of the Chronologue working g ### Function of the Chronologue project +The Chronologue project is a working group within the Good Docs project. +The primary task of the group is to create example documentation to increase the understanding of what good documentation can look like. +The primary purpose is to educate people without a background in technical communication. +The group uses the Good Docs Project’s templates to create these examples, so the secondary purpose of the group is to act as a quality assurance for the Template working group. + +To create credible examples, the group decided to build a fictional product - the Chronologue. The Chronologue is a time-travel telescope that records astronomical events of the future, and past. + +The Chronologue consists of: + +- A time-travel telescope (fictional) +- An API to transmit data between the telescope and the website +- A website to view events recorded by the telescope + + ### Role Matrix ### Writing process From 6ee9cf5e10d64eeb48709cac8aaed553f6e34b64 Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Sat, 10 Sep 2022 12:13:00 -0700 Subject: [PATCH 05/11] Add Role Matrix --- RFC-015-Chronologue.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index fcc35f7..3ee7c00 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -52,6 +52,19 @@ The Chronologue consists of: ### Role Matrix +| Role→
Task↓| Working group lead | Developer | Writer | +| :--- | :----: | :----: | :----: | +| Onboarding new members | X | | | +| Assigning tasks within the group | X | | | +| Creating strategic / administrative documents | X | | | +| Creating internal documentation | X |X| X| +| Writing Chronologue documentation | | | X| +| Web development||X|| +| Website maintenance (Docs & Tool) |X|X|| +| Review PRs |X |X | X| +| Merge PRs |X |X |X | +| Make improvements to the templates| | | X| + ### Writing process ### Mock product: Technical and creative needs and a proposal for tooling From 66597c13de10ac364d4fbc08d3857ae1016d1f61 Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Sat, 10 Sep 2022 13:13:43 -0700 Subject: [PATCH 06/11] Add process --- RFC-015-Chronologue.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index 3ee7c00..3a91161 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -56,7 +56,7 @@ The Chronologue consists of: | :--- | :----: | :----: | :----: | | Onboarding new members | X | | | | Assigning tasks within the group | X | | | -| Creating strategic / administrative documents | X | | | +| Creating strategic / administrative documents like documentation plans, release notes, etc. | X | | | | Creating internal documentation | X |X| X| | Writing Chronologue documentation | | | X| | Web development||X|| @@ -67,6 +67,20 @@ The Chronologue consists of: ### Writing process +The Chronologue working group starts its writing process when the template is in [Phase 6 - Improve the template with user feedback](https://github.com/thegooddocsproject/templates/blob/dev/CONTRIBUTING.md#overview-of-the-template-writing-phases). + +We decided to come in at this late stage because developing good templates is already quite time consuming and we don't want to add to the development cycle. + +The following table describes what happens after a template has been released. + +| Phase | Who does it? | What happens? | +| :--- | :----: | :---- | +|1 - Plan | Working group lead|
  • Add the template to the documentation plan
  • Create an issue to track work
  • Assign content to a writer
    • | +|2 - Draft| Writer|
  • Create a new branch off of [`docs`](https://github.com/thegooddocsproject/chronologue/tree/docs)
  • Create Chronologue documentation using the template
  • Keep a [friction log](https://developerrelations.com/developer-experience/an-introduction-to-friction-logging) of template/guide for later improvements
    • | +|3 - Review | Writer|
  • Create PR against the `docs` branch
  • Assign WG lead or other writer as a reviewer
  • Improve content based on feedback
    • | +|4 - Commentary & Publication |Writer|
  • Add commentary to your content to highlight what makes it good
  • Merge the PR into the `docs` branch to publish the content
    • | +|5 (if applicable) - Template | Writer|
  • In the `templates` repository, create a new branch off of [`dev`](https://github.com/thegooddocsproject/templates)
  • Make changes to the template based on your friction log notes.
  • Create a PR and add the template author as a reviewer
    • | + ### Mock product: Technical and creative needs and a proposal for tooling ## Consequences From c835390340c3bf281039ea9996554c70adfd4986 Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Sat, 10 Sep 2022 13:27:35 -0700 Subject: [PATCH 07/11] Update RFC-015-Chronologue.md --- RFC-015-Chronologue.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index 3a91161..ff9e85f 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -79,7 +79,7 @@ The following table describes what happens after a template has been released. |2 - Draft| Writer|
  • Create a new branch off of [`docs`](https://github.com/thegooddocsproject/chronologue/tree/docs)
  • Create Chronologue documentation using the template
  • Keep a [friction log](https://developerrelations.com/developer-experience/an-introduction-to-friction-logging) of template/guide for later improvements
    • | |3 - Review | Writer|
  • Create PR against the `docs` branch
  • Assign WG lead or other writer as a reviewer
  • Improve content based on feedback
    • | |4 - Commentary & Publication |Writer|
  • Add commentary to your content to highlight what makes it good
  • Merge the PR into the `docs` branch to publish the content
    • | -|5 (if applicable) - Template | Writer|
  • In the `templates` repository, create a new branch off of [`dev`](https://github.com/thegooddocsproject/templates)
  • Make changes to the template based on your friction log notes.
  • Create a PR and add the template author as a reviewer
    • | +|5 (if applicable) - Template improvements | Writer|
  • In the `templates` repository, create a new branch off of [`dev`](https://github.com/thegooddocsproject/templates)
  • Make changes to the template based on your friction log notes.
  • Create a PR and add the template author as a reviewer
    • | ### Mock product: Technical and creative needs and a proposal for tooling @@ -100,9 +100,11 @@ The following table describes what happens after a template has been released. ## Decisions deferred -{This section is option and is where you can list decisions that won't be resolved by this RFC, but which should be raised at a later time.} +While the RFC lays out what the group's purpose is and how it operates, two questions still remain to be answered as of this writing. Both of them touch on topics affect other working groups as well; therefore, these decisions should be made in other RFCs. -- Feedback channel for content (Reason: This should be unified across the sites we maintain?) +- **Onboarding new members**: A bottleneck in onboarding is that the writers and developers need to establish a lot of context before they can make quality contributions. It takes a lot of time to get members into a state where they can make contributions. In the past, the working group lead onboarded members personally - mostly because of the group's velocity. Since this RFC establishes a basic understanding of the group, we could develop more text-based onboarding materials, including internal documentation. + +- **Feedback channels**: ## Feedback From 7ea8effe38741f006225808cecaabe33d0a4316f Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Sat, 10 Sep 2022 19:04:34 -0700 Subject: [PATCH 08/11] Add consequences --- RFC-015-Chronologue.md | 43 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index ff9e85f..8c1f56c 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -83,14 +83,50 @@ The following table describes what happens after a template has been released. ### Mock product: Technical and creative needs and a proposal for tooling +We want to follow good engineering practice, therefore this section separates our needs from the implementation. +That way, we can make sure that we choose appropriately for our current needs and can check in if the implementation still fits when needs change. + +The Chronologue working group develops its mock tool on the [`main`](https://github.com/thegooddocsproject/chronologue) branch in the Chronologue repository. + +#### Needs: + +* Framework/tool that allows for dynamic web page templating, since we want to pull in data from an API +* Needs to work with our hosting platform (Currently: Netlify OSS plan) +* Framework & knowledge support: Tool(s) need to be actively maintained and adopted by a large community. Larger projects often receive more support, and questions can be addressed by fellow community members. +* Tool(s) need good documentation. +* Tech implementation should invite and onboard technical writers easily for maintenance later on. This can be mitigated by creating internal docs. + +#### Possible technical implementation: + +The group leans towards the following implementation, since it has to build a page according to a [mockup](https://www.figma.com/proto/lvaAChlbueycET2ws9ZquS/Chronologue?node-id=902%3A1745&scaling=min-zoom&page-id=902%3A1640&starting-point-node-id=902%3A1745) created by Ulises de la Luz and Serena Jolley. + +Ian’s note: will experiment with data fetching + templating + page routing on Hugo + ## Consequences -{Explain what impact this proposal will have on the community, both positive and negative.} +### Positive impact + +The proposal contributes to a better understanding of the Chronologue project’s responsibilities, ambitions, and ways of working. +Furthermore, it establishes a firm foundation on which the working group can rely on when making future decisions. +With this RFC, we aim to ensure a smoother process to create usable, understandable examples for people that want to use the Good Docs Project’s templates. + +### Possible negative impact +The mock tool website poses a possible risk to the maintainablity of the fake tool. Since we want to divert from standard tooling (staticly generated site using HUGO), it can become a bottleneck if knowledgable members of the working group become unavailable. +If we lose critical knowledge, we become less agile when it comes to resolving bugs or further development. + +### Mitigation strategy +To mitigate the risk of losing knowledgable members and becoming immobile, we want to supply comprehensive internal documentation about: + +* The framework we are working with and deviations from standard implementation (if applicable) +* How the repository is organized +* How we approached the CSS and how its related to our source code +* How to maintain vital parts of the website, including security updates of the framework and dependencies +* A reference document with links to more in-depth resources. ## Links and prior art -{This section is optional if you want to [link](https://example.com) to other resources.} +[Chronologue Figma Mockup]([https://example.com](https://www.figma.com/proto/lvaAChlbueycET2ws9ZquS/Chronologue?node-id=902%3A1745&scaling=min-zoom&page-id=902%3A1640&starting-point-node-id=902%3A1745) created by Ulises de la Luz and Serena Jolley. ## Open questions @@ -104,8 +140,7 @@ While the RFC lays out what the group's purpose is and how it operates, two ques - **Onboarding new members**: A bottleneck in onboarding is that the writers and developers need to establish a lot of context before they can make quality contributions. It takes a lot of time to get members into a state where they can make contributions. In the past, the working group lead onboarded members personally - mostly because of the group's velocity. Since this RFC establishes a basic understanding of the group, we could develop more text-based onboarding materials, including internal documentation. -- **Feedback channels**: - +- **Feedback channels**: Once we publish templates and example content, and our audience interacts with them, they might want to give feedback. Instead of being angrily tweeted at, we might want to establish dedicated feedback channels. A possible solution could be an embedded form at the bottom of a page so that we get. This would allow us to get feedback specific to our content or template. However, to have a consistent UX, we should discuss how to create consistent feedback channels across our sites. ## Feedback From de7269113b2c9ab8c30e16ab6b88621e7e1abb5b Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Sat, 10 Sep 2022 19:19:23 -0700 Subject: [PATCH 09/11] Update RFC-015-Chronologue.md --- RFC-015-Chronologue.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index 8c1f56c..19ec811 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -98,9 +98,16 @@ The Chronologue working group develops its mock tool on the [`main`](https://git #### Possible technical implementation: -The group leans towards the following implementation, since it has to build a page according to a [mockup](https://www.figma.com/proto/lvaAChlbueycET2ws9ZquS/Chronologue?node-id=902%3A1745&scaling=min-zoom&page-id=902%3A1640&starting-point-node-id=902%3A1745) created by Ulises de la Luz and Serena Jolley. +Since we have to build a website according to the [Chronologue mockup](https://www.figma.com/proto/lvaAChlbueycET2ws9ZquS/Chronologue?node-id=902%3A1745&scaling=min-zoom&page-id=902%3A1640&starting-point-node-id=902%3A1745), we lean towards the following implementation: + +**Next.js** as our web development framework. It comes with a templating language and supports dynamic data fetching. Next.js is a mature project with extensive [documentation](https://nextjs.org/docs). It can be easily deployed through Netlify. + +We are aware that deviating from our standard tech stack comes with risk. +Ian, Chronologue's web developer, is open to experiment with data fetching, templating and page routing with HUGO. +However, even if HUGO supports all our needs, it might not be worthwhile to switch, since development started already. +The web development team is small (1-2 people) and they would need to refactor the whole code base, delaying the deployment date. +Opposed to the Chronologue documentation, we don't anticipate that the mock tool needs much attention after it has been published. -Ian’s note: will experiment with data fetching + templating + page routing on Hugo ## Consequences From aae26eb6820c68c4892e1b072568014d059cda87 Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Sat, 10 Sep 2022 19:23:46 -0700 Subject: [PATCH 10/11] Update RFC-015-Chronologue.md --- RFC-015-Chronologue.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index 19ec811..3028471 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -67,6 +67,8 @@ The Chronologue consists of: ### Writing process +The writers write in Markdown and store their documentation on the [`docs`](https://github.com/thegooddocsproject/chronologue/tree/docs) branch on Github. We use HUGO as a static site generator for the documentation as we regularly update the docs and it is the project's standard tool. + The Chronologue working group starts its writing process when the template is in [Phase 6 - Improve the template with user feedback](https://github.com/thegooddocsproject/templates/blob/dev/CONTRIBUTING.md#overview-of-the-template-writing-phases). We decided to come in at this late stage because developing good templates is already quite time consuming and we don't want to add to the development cycle. @@ -119,7 +121,7 @@ With this RFC, we aim to ensure a smoother process to create usable, understanda ### Possible negative impact -The mock tool website poses a possible risk to the maintainablity of the fake tool. Since we want to divert from standard tooling (staticly generated site using HUGO), it can become a bottleneck if knowledgable members of the working group become unavailable. +The mock tool website poses a possible risk to the maintainability of the fake tool. Since we want to divert from standard tooling (static generated site using HUGO), it can become a bottleneck if knowledgable members of the working group become unavailable. If we lose critical knowledge, we become less agile when it comes to resolving bugs or further development. ### Mitigation strategy From b4ce3b3317ac802d2871069ad8985abc872f6485 Mon Sep 17 00:00:00 2001 From: Tina Luedtke Date: Sat, 10 Sep 2022 19:33:48 -0700 Subject: [PATCH 11/11] Update RFC-015-Chronologue.md --- RFC-015-Chronologue.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/RFC-015-Chronologue.md b/RFC-015-Chronologue.md index 3028471..409de4a 100644 --- a/RFC-015-Chronologue.md +++ b/RFC-015-Chronologue.md @@ -102,7 +102,7 @@ The Chronologue working group develops its mock tool on the [`main`](https://git Since we have to build a website according to the [Chronologue mockup](https://www.figma.com/proto/lvaAChlbueycET2ws9ZquS/Chronologue?node-id=902%3A1745&scaling=min-zoom&page-id=902%3A1640&starting-point-node-id=902%3A1745), we lean towards the following implementation: -**Next.js** as our web development framework. It comes with a templating language and supports dynamic data fetching. Next.js is a mature project with extensive [documentation](https://nextjs.org/docs). It can be easily deployed through Netlify. +**Next.js** is our web development framework. It comes with a templating language and supports dynamic data fetching. Next.js is a mature project with extensive [documentation](https://nextjs.org/docs) and a large community. It can be easily deployed through Netlify and can auto-translate to Netlify's API functions. We are aware that deviating from our standard tech stack comes with risk. Ian, Chronologue's web developer, is open to experiment with data fetching, templating and page routing with HUGO. @@ -110,6 +110,11 @@ However, even if HUGO supports all our needs, it might not be worthwhile to swit The web development team is small (1-2 people) and they would need to refactor the whole code base, delaying the deployment date. Opposed to the Chronologue documentation, we don't anticipate that the mock tool needs much attention after it has been published. +There are many alternatives out there, so here is a short summary of what tools we looked at and our thoughts: + +* Vue.js: similar to Next.js, but uses a different way to template and implement features like routing, data fetching, and state management. Also has enthusiast devs working on it. +* SvelteKit: relatively player with an interesting tech implementation. Seems to miss crucial features like routing, etc. SDK not in production mode yet. +* Hugo: a static site generator works well with Netlify and has a web templating language. Unclear about routing, and data fetching. ## Consequences @@ -124,7 +129,7 @@ With this RFC, we aim to ensure a smoother process to create usable, understanda The mock tool website poses a possible risk to the maintainability of the fake tool. Since we want to divert from standard tooling (static generated site using HUGO), it can become a bottleneck if knowledgable members of the working group become unavailable. If we lose critical knowledge, we become less agile when it comes to resolving bugs or further development. -### Mitigation strategy +### Mitigation strategy To mitigate the risk of losing knowledgable members and becoming immobile, we want to supply comprehensive internal documentation about: * The framework we are working with and deviations from standard implementation (if applicable) @@ -161,10 +166,7 @@ If you reject feedback, note that rejected feedback here before resolving the co If this proposal is accepted, the following tasks must be completed: -- [ ] Task number one -- [ ] Task number two -- [ ] Task number three, etc. - +- [ ] Create detailed documentation for our infrastructure on the `main` branch, see [Mitigation strategy](#mitigation). ## Votes