From 1d677e4bef9a4915865feccb641fb23b7175d002 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Mon, 19 Jan 2026 17:18:15 +0000 Subject: [PATCH 01/18] Initial draft on repo documentation guidance --- repo-documentation.md | 96 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 repo-documentation.md diff --git a/repo-documentation.md b/repo-documentation.md new file mode 100644 index 0000000..5db9d70 --- /dev/null +++ b/repo-documentation.md @@ -0,0 +1,96 @@ +# Repo Documentation + +Repos are often the first place an engineer will look for documentation on a project. Effective technical documentation +is a gift to your future self, and will save you and others time. + +## Overall guidance + +### Writing good documentation is challenging + +Writing effective documentation is challenging and requires time and investment. Google offer helpful resources that +provide practical advice for writing quality documentation. See +the [Technical Writing One](https://developers.google.com/tech-writing/one?_gl=1*k0cdlv*_up*MQ..*_ga*NDcwODc0MjQ4LjE3Njg4NDAxNjc.*_ga_SM8HXJ53K2*czE3Njg4NDAxNjckbzEkZzAkdDE3Njg4NDAxNjckajYwJGwwJGgw) +materials for improving your technical writing skills. + +### Write for an audience + + +Repo documentation is primarily useful for engineers. But, authors should also consider the value it provides product +and engineering managers. When documentation is written clearly, it provides a useful resource for a multitude of +readers with a variety of technical skill and levels of domain knowledge. It can save time by answering the most +important questions in a concise way. + + +> As experts, it is easy to forget that +> novices don’t know what you already know. Novices might not understand explanations that make passing reference to +> subtle interactions and deep systems that the expert doesn’t stop to explain. + +– [Technical Writing One / Audience](https://developers.google.com/tech-writing/one/audience?_gl=1*1nxkafc*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#curse_of_knowledge) + +Consider how and why a person is reading documentation, what questions and objectives may they have? What might readers +be expected to already know and what does the documentation aim to teach them? + +> Answering the following questions helps you determine what your document should contain: +> +> - Who is your target audience? +> - What is your target audience's goal? Why are they reading this document? +> - What do your readers already know before they read your document? +> - What should your readers know or be able to do after they read your document + +– [Technical Writing One / Documents](https://developers.google.com/tech-writing/one/documents?_gl=1*1euylx7*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#write_for_your_audience) + +### Including hyperlinks + +Hyperlinks to other projects, documentation, or samples of key code snippets, reduce repetition. They provide +users the means to access relevant resources. Therefore, linking allows the author to make assumptions about the readers +knowledge by specifying prerequisites for the content. For example: + +> The [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) (AWS CDK) is an open-source software +> development framework to define cloud infrastructure in code and provision it +> through AWS CloudFormation. +> +>`@guardian/cdk` builds on CDK to provide Guardian-specific [patterns](./src/patterns) and +[constructs](./src/constructs). It is an opinionated and secure-by-default way to describe and +> provision your AWS resources. + +### Define new or unfamiliar terms + +Authors often forget the terms and phrases they may use every day that might be unfamiliar to outsiders or newcomers. +Defining these terms can provide significant clarity for experts and novices alike. + +> When writing or editing, learn to recognize terms that might be unfamiliar to some or all of your target audience. +> When you spot such a term, take one of the following two tactics: +> +> - If the term already exists, link to a good existing explanation. (Don't reinvent the wheel.) +> - If your document is introducing the term, define the term. If your document is introducing many terms, collect the +> definitions into a glossary. + +– [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words?_gl=1*4d3vld*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MjM5MjAkbzEkZzAkdDE3Njg4MjQxMzkkajYwJGwwJGgw#define_new_or_unfamiliar_terms) + +Acronyms can abbreviate and simplify documentation. However, it can also create barriers to entry for an unfamiliar +audience. + + +> Sure, you can introduce and use acronyms properly, but should you use acronyms? Well, acronyms do reduce sentence +> size. For example, TTN is two words shorter than Telekinetic Tactile Network. However, acronyms are really just a +> layer +> of abstraction; readers must mentally expand recently learned acronyms to the full term. For example, readers convert +> TTN to Telekinetic Tactile Network in their heads, so the "shorter" acronym actually takes a little longer to process +> than the full term. + +– [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words?_gl=1*154isid*_up*MQ..*_ga*Mzg0NzExNTA2LjE3Njg4NDIzMTA.*_ga_SM8HXJ53K2*czE3Njg4NDIzMTAkbzEkZzAkdDE3Njg4NDIzMTAkajYwJGwwJGgw#use_acronyms_properly) + +### Illustrations, list and tables + + +Complex information can be more effectively structured than through blocks of text. Illustrations, diagrams and tables +break up the text and allows readers to identify the most relevant information. When writing documentation, consider how +a diagram can clearly explain intricate UI, concepts, or relationships. + +> Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes +> zoom towards the table. + +– [Technical Writing One / Tables](https://developers.google.com/tech-writing/one/lists-and-tables?_gl=1*11yvapt*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#create_useful_tables) + + + From 00a121245bf4a7a301a15be8aaf0dd76a71de2f8 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Tue, 20 Jan 2026 08:42:18 +0000 Subject: [PATCH 02/18] Adds initial README template to the documentation --- repo-documentation.md | 152 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 124 insertions(+), 28 deletions(-) diff --git a/repo-documentation.md b/repo-documentation.md index 5db9d70..6d41081 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -1,35 +1,45 @@ # Repo Documentation -Repos are often the first place an engineer will look for documentation on a project. Effective technical documentation -is a gift to your future self, and will save you and others time. +Repositories are often the first place an engineer will look for documentation on a project. Effective technical +documentation is a gift to your future self, and will save you and others time. -## Overall guidance +The following content provides practical advice on writing high quality technical documentation with a recommended +structure for the base README file of a repo. + +## Contents + +- [Overall guidance](#overall-guidance) +- [README Template](#readme-template) + +## Overall Guidance ### Writing good documentation is challenging -Writing effective documentation is challenging and requires time and investment. Google offer helpful resources that -provide practical advice for writing quality documentation. See +Writing effective documentation is challenging and requires time and investment. It is a skill which requires practice +and effort to improve on. Google offers helpful resources that provide advice for writing quality documentation. See the [Technical Writing One](https://developers.google.com/tech-writing/one?_gl=1*k0cdlv*_up*MQ..*_ga*NDcwODc0MjQ4LjE3Njg4NDAxNjc.*_ga_SM8HXJ53K2*czE3Njg4NDAxNjckbzEkZzAkdDE3Njg4NDAxNjckajYwJGwwJGgw) materials for improving your technical writing skills. ### Write for an audience -Repo documentation is primarily useful for engineers. But, authors should also consider the value it provides product -and engineering managers. When documentation is written clearly, it provides a useful resource for a multitude of -readers with a variety of technical skill and levels of domain knowledge. It can save time by answering the most +Repo documentation is primarily useful for engineers. However, authors should also consider the value it provides to +product and engineering managers. When documentation is written clearly, it provides a useful resource for a multitude +of readers with varying levels of technical skill and domain knowledge. It can save time by answering the most important questions in a concise way. -> As experts, it is easy to forget that -> novices don’t know what you already know. Novices might not understand explanations that make passing reference to -> subtle interactions and deep systems that the expert doesn’t stop to explain. +> [!WARNING] +> As experts, it is easy to forget that novices don’t know what you already know. Novices might not understand +> explanations that make passing reference to subtle interactions and deep systems that the expert doesn’t stop to +> explain. – [Technical Writing One / Audience](https://developers.google.com/tech-writing/one/audience?_gl=1*1nxkafc*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#curse_of_knowledge) -Consider how and why a person is reading documentation, what questions and objectives may they have? What might readers -be expected to already know and what does the documentation aim to teach them? +Consider how and why someone is reading the documentation. What questions and objectives may they have? What might +readers be expected to already know and what does the documentation aim to teach them? +> [!TIP] > Answering the following questions helps you determine what your document should contain: > > - Who is your target audience? @@ -41,9 +51,9 @@ be expected to already know and what does the documentation aim to teach them? ### Including hyperlinks -Hyperlinks to other projects, documentation, or samples of key code snippets, reduce repetition. They provide -users the means to access relevant resources. Therefore, linking allows the author to make assumptions about the readers -knowledge by specifying prerequisites for the content. For example: +Hyperlinks to other projects, documentation, or samples of key code snippets, reduce repetition and provide users with +access to relevant resource. Linking allows the author to make assumptions about the readers knowledge by specifying +prerequisites for the content. For example: > The [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) (AWS CDK) is an open-source software > development framework to define cloud infrastructure in code and provision it @@ -53,44 +63,130 @@ knowledge by specifying prerequisites for the content. For example: [constructs](./src/constructs). It is an opinionated and secure-by-default way to describe and > provision your AWS resources. +– [Guardian CDK Library](https://github.com/guardian/cdk?tab=readme-ov-file#guardian-cdk-library) + ### Define new or unfamiliar terms -Authors often forget the terms and phrases they may use every day that might be unfamiliar to outsiders or newcomers. -Defining these terms can provide significant clarity for experts and novices alike. +Authors often forget the terms and phrases they use daily that might be unfamiliar to outsiders or newcomers. Defining +these terms can provide significant clarity for experts and novices alike. +> [!TIP] > When writing or editing, learn to recognize terms that might be unfamiliar to some or all of your target audience. > When you spot such a term, take one of the following two tactics: > > - If the term already exists, link to a good existing explanation. (Don't reinvent the wheel.) > - If your document is introducing the term, define the term. If your document is introducing many terms, collect the -> definitions into a glossary. + > definitions into a glossary. – [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words?_gl=1*4d3vld*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MjM5MjAkbzEkZzAkdDE3Njg4MjQxMzkkajYwJGwwJGgw#define_new_or_unfamiliar_terms) -Acronyms can abbreviate and simplify documentation. However, it can also create barriers to entry for an unfamiliar +Acronyms can abbreviate and simplify documentation, but it can also create barriers to entry for an unfamiliar audience. +> [!TIP] > Sure, you can introduce and use acronyms properly, but should you use acronyms? Well, acronyms do reduce sentence > size. For example, TTN is two words shorter than Telekinetic Tactile Network. However, acronyms are really just a -> layer -> of abstraction; readers must mentally expand recently learned acronyms to the full term. For example, readers convert -> TTN to Telekinetic Tactile Network in their heads, so the "shorter" acronym actually takes a little longer to process -> than the full term. +> layer of abstraction; readers must mentally expand recently learned acronyms to the full term. For example, readers +> convert TTN to Telekinetic Tactile Network in their heads, so the "shorter" acronym actually takes a little longer to +> process than the full term. – [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words?_gl=1*154isid*_up*MQ..*_ga*Mzg0NzExNTA2LjE3Njg4NDIzMTA.*_ga_SM8HXJ53K2*czE3Njg4NDIzMTAkbzEkZzAkdDE3Njg4NDIzMTAkajYwJGwwJGgw#use_acronyms_properly) -### Illustrations, list and tables +### Illustrations, lists and tables -Complex information can be more effectively structured than through blocks of text. Illustrations, diagrams and tables -break up the text and allows readers to identify the most relevant information. When writing documentation, consider how -a diagram can clearly explain intricate UI, concepts, or relationships. +Complex information can often be better understood when presented in a structured format rather than in large blocks of +text Illustrations, diagrams and tables break up the text and allows readers to identify the most relevant information. +When writing documentation, consider how a diagram can clearly explain intricate UI, concepts, or relationships. +> [!TIP] > Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes > zoom towards the table. – [Technical Writing One / Tables](https://developers.google.com/tech-writing/one/lists-and-tables?_gl=1*11yvapt*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#create_useful_tables) +## README Template + +The following template provides a starting point for adding documentation to a new or existing repo. By filling out each +section an author should be confident that they have documented some of the most important aspects of a project. This +template is not intended to replace all other documentation but rather provide a starting point for the opening README. + +```markdown +# [Project Title] + +[Top-level description] + + + +## Contents + +- [Introduction](#1-introduction) +- [Getting Started](#2-getting-started) +- [How It Works](#3-how-it-works) +- [Useful Links](#4-useful-links) +- [Terminology](#5-terminology) + +## 1. Introduction + + + +## 2. Getting Started + + + +## 3. How It Works + + + +## 4. Useful Links + + + +## 5. Terminology + +``` \ No newline at end of file From af01da8d719641c01e9be4adc5f676a41e9fb2a6 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Tue, 20 Jan 2026 11:26:38 +0000 Subject: [PATCH 03/18] Update repo-documentation.md Co-authored-by: TJ Silver <15648334+tjsilver@users.noreply.github.com> --- repo-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-documentation.md b/repo-documentation.md index 6d41081..bb95b7f 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -45,7 +45,7 @@ readers be expected to already know and what does the documentation aim to teach > - Who is your target audience? > - What is your target audience's goal? Why are they reading this document? > - What do your readers already know before they read your document? -> - What should your readers know or be able to do after they read your document +> - What should your readers know or be able to do after they read your document? – [Technical Writing One / Documents](https://developers.google.com/tech-writing/one/documents?_gl=1*1euylx7*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#write_for_your_audience) From ed993d506cb44ed8c97debb97ed306def05b5057 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Tue, 20 Jan 2026 11:26:59 +0000 Subject: [PATCH 04/18] Update repo-documentation.md Co-authored-by: TJ Silver <15648334+tjsilver@users.noreply.github.com> --- repo-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-documentation.md b/repo-documentation.md index bb95b7f..ccdad61 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -52,7 +52,7 @@ readers be expected to already know and what does the documentation aim to teach ### Including hyperlinks Hyperlinks to other projects, documentation, or samples of key code snippets, reduce repetition and provide users with -access to relevant resource. Linking allows the author to make assumptions about the readers knowledge by specifying +access to relevant resources. Linking allows the author to make assumptions about the reader's/readers' knowledge by specifying prerequisites for the content. For example: > The [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) (AWS CDK) is an open-source software From 4fcaa7a7b36581efe3d02835d5d805bc34782d59 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Tue, 20 Jan 2026 11:27:11 +0000 Subject: [PATCH 05/18] Update repo-documentation.md Co-authored-by: TJ Silver <15648334+tjsilver@users.noreply.github.com> --- repo-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-documentation.md b/repo-documentation.md index ccdad61..77e2d6a 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -80,7 +80,7 @@ these terms can provide significant clarity for experts and novices alike. – [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words?_gl=1*4d3vld*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MjM5MjAkbzEkZzAkdDE3Njg4MjQxMzkkajYwJGwwJGgw#define_new_or_unfamiliar_terms) -Acronyms can abbreviate and simplify documentation, but it can also create barriers to entry for an unfamiliar +Acronyms can abbreviate and simplify documentation, but they can also create barriers to entry for an unfamiliar audience. From b01c9978174ba3d6c68b9db3edbd45c9ed4bc3fc Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Tue, 20 Jan 2026 11:27:25 +0000 Subject: [PATCH 06/18] Update repo-documentation.md Co-authored-by: TJ Silver <15648334+tjsilver@users.noreply.github.com> --- repo-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-documentation.md b/repo-documentation.md index 77e2d6a..49477ad 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -97,7 +97,7 @@ audience. Complex information can often be better understood when presented in a structured format rather than in large blocks of -text Illustrations, diagrams and tables break up the text and allows readers to identify the most relevant information. +text. Illustrations, diagrams and tables break up the text and allow readers to identify the most relevant information. When writing documentation, consider how a diagram can clearly explain intricate UI, concepts, or relationships. > [!TIP] From 2b073649063794aefc9b2ee4176d498931952a7c Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Mon, 26 Jan 2026 14:55:24 +0000 Subject: [PATCH 07/18] Update repo-documentation.md Co-authored-by: Natasha <67543397+NovemberTang@users.noreply.github.com> --- repo-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-documentation.md b/repo-documentation.md index 49477ad..524dd4e 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -17,7 +17,7 @@ structure for the base README file of a repo. Writing effective documentation is challenging and requires time and investment. It is a skill which requires practice and effort to improve on. Google offers helpful resources that provide advice for writing quality documentation. See -the [Technical Writing One](https://developers.google.com/tech-writing/one?_gl=1*k0cdlv*_up*MQ..*_ga*NDcwODc0MjQ4LjE3Njg4NDAxNjc.*_ga_SM8HXJ53K2*czE3Njg4NDAxNjckbzEkZzAkdDE3Njg4NDAxNjckajYwJGwwJGgw) +the [Technical Writing One](https://developers.google.com/tech-writing/one) materials for improving your technical writing skills. ### Write for an audience From 398a88b198e58927d69897b2ba7ec1dbdd8d0f2d Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Mon, 26 Jan 2026 14:58:18 +0000 Subject: [PATCH 08/18] Removes google tech-writing query params --- repo-documentation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/repo-documentation.md b/repo-documentation.md index 524dd4e..71201c8 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -34,7 +34,7 @@ important questions in a concise way. > explanations that make passing reference to subtle interactions and deep systems that the expert doesn’t stop to > explain. -– [Technical Writing One / Audience](https://developers.google.com/tech-writing/one/audience?_gl=1*1nxkafc*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#curse_of_knowledge) +– [Technical Writing One / Audience](https://developers.google.com/tech-writing/one/audience#curse_of_knowledge) Consider how and why someone is reading the documentation. What questions and objectives may they have? What might readers be expected to already know and what does the documentation aim to teach them? @@ -47,7 +47,7 @@ readers be expected to already know and what does the documentation aim to teach > - What do your readers already know before they read your document? > - What should your readers know or be able to do after they read your document? -– [Technical Writing One / Documents](https://developers.google.com/tech-writing/one/documents?_gl=1*1euylx7*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#write_for_your_audience) +– [Technical Writing One / Documents](https://developers.google.com/tech-writing/one/documents#write_for_your_audience) ### Including hyperlinks @@ -78,7 +78,7 @@ these terms can provide significant clarity for experts and novices alike. > - If your document is introducing the term, define the term. If your document is introducing many terms, collect the > definitions into a glossary. -– [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words?_gl=1*4d3vld*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MjM5MjAkbzEkZzAkdDE3Njg4MjQxMzkkajYwJGwwJGgw#define_new_or_unfamiliar_terms) +– [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words#define_new_or_unfamiliar_terms) Acronyms can abbreviate and simplify documentation, but they can also create barriers to entry for an unfamiliar audience. @@ -91,7 +91,7 @@ audience. > convert TTN to Telekinetic Tactile Network in their heads, so the "shorter" acronym actually takes a little longer to > process than the full term. -– [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words?_gl=1*154isid*_up*MQ..*_ga*Mzg0NzExNTA2LjE3Njg4NDIzMTA.*_ga_SM8HXJ53K2*czE3Njg4NDIzMTAkbzEkZzAkdDE3Njg4NDIzMTAkajYwJGwwJGgw#use_acronyms_properly) +– [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words#use_acronyms_properly) ### Illustrations, lists and tables @@ -104,7 +104,7 @@ When writing documentation, consider how a diagram can clearly explain intricate > Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes > zoom towards the table. -– [Technical Writing One / Tables](https://developers.google.com/tech-writing/one/lists-and-tables?_gl=1*11yvapt*_up*MQ..*_ga*NTc1NTM3MzgwLjE3Njg4MjM5MjA.*_ga_SM8HXJ53K2*czE3Njg4MzE3MTQkbzIkZzAkdDE3Njg4MzM0ODMkajYwJGwwJGgw#create_useful_tables) +– [Technical Writing One / Tables](https://developers.google.com/tech-writing/one/lists-and-tables#create_useful_tables) ## README Template From 9a1a8a28f91f959ca7d9bd95f36c1c2f35aa3b79 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Mon, 26 Jan 2026 15:10:45 +0000 Subject: [PATCH 09/18] Add a recommendaiton to define your audience in repo documentation --- repo-documentation.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/repo-documentation.md b/repo-documentation.md index 71201c8..2d14de2 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -37,7 +37,10 @@ important questions in a concise way. – [Technical Writing One / Audience](https://developers.google.com/tech-writing/one/audience#curse_of_knowledge) Consider how and why someone is reading the documentation. What questions and objectives may they have? What might -readers be expected to already know and what does the documentation aim to teach them? +readers be expected to already know and what does the documentation aim to teach them? The definition of your audience +and intent of the documentation can be included in your introduction which will also make it clear to readers. If they +are in the wrong place, a [helpful hyperlink](#including-hyperlinks) may be able to help them on their way to more +relevant information. > [!TIP] > Answering the following questions helps you determine what your document should contain: @@ -52,8 +55,8 @@ readers be expected to already know and what does the documentation aim to teach ### Including hyperlinks Hyperlinks to other projects, documentation, or samples of key code snippets, reduce repetition and provide users with -access to relevant resources. Linking allows the author to make assumptions about the reader's/readers' knowledge by specifying -prerequisites for the content. For example: +access to relevant resources. Linking allows the author to make assumptions about the reader's/readers' knowledge by +specifying prerequisites for the content. For example: > The [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) (AWS CDK) is an open-source software > development framework to define cloud infrastructure in code and provision it @@ -137,6 +140,7 @@ The section should provide a clear explanation for why the project exists and wh Areas to include: - Who is the intended audience for the project? + - Who should read this documentation (users, engineers, managers)? - What core features does the project provide? - Why was the project made? - Which other services does it integrate with (provide links)? From b91c7ae5b3a2545b8777878b2fe55e14839c37b7 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Mon, 26 Jan 2026 15:44:14 +0000 Subject: [PATCH 10/18] Adds detail about markdown features to repo documentation doc --- repo-documentation.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/repo-documentation.md b/repo-documentation.md index 2d14de2..aa2c455 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -103,6 +103,12 @@ Complex information can often be better understood when presented in a structure text. Illustrations, diagrams and tables break up the text and allow readers to identify the most relevant information. When writing documentation, consider how a diagram can clearly explain intricate UI, concepts, or relationships. +Markdown provides a variety of features to format your documentation with GitHub offering +their [own set of additional features](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). +These features can be used to strucutre, emphasize, and +even [collapse](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) +information. + > [!TIP] > Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes > zoom towards the table. From 145806448e7c987039be5735a50a0273c79ad287 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Wed, 28 Jan 2026 08:48:26 +0000 Subject: [PATCH 11/18] Update repo-documentation.md Co-authored-by: Emily Bourke --- repo-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-documentation.md b/repo-documentation.md index aa2c455..248b25d 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -3,7 +3,7 @@ Repositories are often the first place an engineer will look for documentation on a project. Effective technical documentation is a gift to your future self, and will save you and others time. -The following content provides practical advice on writing high quality technical documentation with a recommended +This document provides practical advice on writing high quality technical documentation with a recommended structure for the base README file of a repo. ## Contents From d82657a032559816d951f6aa1418a21d757b8824 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Wed, 28 Jan 2026 08:56:27 +0000 Subject: [PATCH 12/18] Fix rogue > in repo documentation --- repo-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-documentation.md b/repo-documentation.md index 248b25d..f787d21 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -79,7 +79,7 @@ these terms can provide significant clarity for experts and novices alike. > > - If the term already exists, link to a good existing explanation. (Don't reinvent the wheel.) > - If your document is introducing the term, define the term. If your document is introducing many terms, collect the - > definitions into a glossary. + definitions into a glossary. – [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words#define_new_or_unfamiliar_terms) From 467edd32fb4b274cb40ec5692d773e50d58502d8 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Wed, 28 Jan 2026 09:38:00 +0000 Subject: [PATCH 13/18] Includes why writing for an audience is valuable in repo documentation --- repo-documentation.md | 43 ++++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/repo-documentation.md b/repo-documentation.md index f787d21..0ed8fd9 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -22,11 +22,21 @@ materials for improving your technical writing skills. ### Write for an audience - -Repo documentation is primarily useful for engineers. However, authors should also consider the value it provides to -product and engineering managers. When documentation is written clearly, it provides a useful resource for a multitude -of readers with varying levels of technical skill and domain knowledge. It can save time by answering the most -important questions in a concise way. +Before authors can provide practical information to readers, they need to consider: + + - Who is their target audience? + - What is their target audience's goal? Why are they reading this document? + - What do readers already know before they read your document? + - What should readers know or be able to do after they read your document? + +Answering these questions allows an author to know what is relevant and reasonable to assume about readers. This helps +to keep documentation concise and focused. Assuming too much will make the documentation difficult to engage with, +whereas too little will make it overly verbose. + +The assumptions made about reader should be tested through a review process. Reviewers should be transparent about areas +they found confusing or irrelevant. Identifying these areas in the documentation is the most helpful feedback an author +can receive. It allows an author to consider their real audience and work with them to provide the right level of +detail. > [!WARNING] @@ -36,21 +46,16 @@ important questions in a concise way. – [Technical Writing One / Audience](https://developers.google.com/tech-writing/one/audience#curse_of_knowledge) -Consider how and why someone is reading the documentation. What questions and objectives may they have? What might -readers be expected to already know and what does the documentation aim to teach them? The definition of your audience -and intent of the documentation can be included in your introduction which will also make it clear to readers. If they -are in the wrong place, a [helpful hyperlink](#including-hyperlinks) may be able to help them on their way to more -relevant information. -> [!TIP] -> Answering the following questions helps you determine what your document should contain: -> -> - Who is your target audience? -> - What is your target audience's goal? Why are they reading this document? -> - What do your readers already know before they read your document? -> - What should your readers know or be able to do after they read your document? - -– [Technical Writing One / Documents](https://developers.google.com/tech-writing/one/documents#write_for_your_audience) + +Repo documentation is primarily useful for engineers. However, authors should consider the value it provides to product +and engineering managers. When documentation is written clearly, it provides a useful resource for a multitude of +readers with varying levels of technical skill and domain knowledge. It can save time by answering the most important +questions in a concise way. + +The definition of your audience and intent of the documentation can be included in your introduction which will also +make it clear to readers. If they are in the wrong place, a [helpful hyperlink](#including-hyperlinks) may be able to +help them on their way to more relevant information. ### Including hyperlinks From 886a5de38a803f06741c9dac56ace755ae4d6132 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Wed, 28 Jan 2026 11:35:02 +0000 Subject: [PATCH 14/18] Update repo-documentation.md Co-authored-by: Emily Bourke --- repo-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/repo-documentation.md b/repo-documentation.md index 0ed8fd9..681bdf0 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -110,7 +110,7 @@ When writing documentation, consider how a diagram can clearly explain intricate Markdown provides a variety of features to format your documentation with GitHub offering their [own set of additional features](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). -These features can be used to strucutre, emphasize, and +These features can be used to structure, emphasize, and even [collapse](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) information. From 89e3c3a209ba7fe1e77bf4def5677016e2bcf037 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Thu, 5 Feb 2026 09:15:25 +0000 Subject: [PATCH 15/18] Add reference to Mermaid diagrams in documentation illustration guidance --- repo-documentation.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/repo-documentation.md b/repo-documentation.md index 681bdf0..10a7ad8 100644 --- a/repo-documentation.md +++ b/repo-documentation.md @@ -24,10 +24,10 @@ materials for improving your technical writing skills. Before authors can provide practical information to readers, they need to consider: - - Who is their target audience? - - What is their target audience's goal? Why are they reading this document? - - What do readers already know before they read your document? - - What should readers know or be able to do after they read your document? +- Who is their target audience? +- What is their target audience's goal? Why are they reading this document? +- What do readers already know before they read your document? +- What should readers know or be able to do after they read your document? Answering these questions allows an author to know what is relevant and reasonable to assume about readers. This helps to keep documentation concise and focused. Assuming too much will make the documentation difficult to engage with, @@ -95,7 +95,7 @@ audience. > [!TIP] > Sure, you can introduce and use acronyms properly, but should you use acronyms? Well, acronyms do reduce sentence > size. For example, TTN is two words shorter than Telekinetic Tactile Network. However, acronyms are really just a -> layer of abstraction; readers must mentally expand recently learned acronyms to the full term. For example, readers +> layer of abstraction; readers must mentally expand recently learned [unfamiliar] acronyms to the full term. For example, readers > convert TTN to Telekinetic Tactile Network in their heads, so the "shorter" acronym actually takes a little longer to > process than the full term. @@ -112,13 +112,9 @@ Markdown provides a variety of features to format your documentation with GitHub their [own set of additional features](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). These features can be used to structure, emphasize, and even [collapse](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) -information. - -> [!TIP] -> Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes -> zoom towards the table. - -– [Technical Writing One / Tables](https://developers.google.com/tech-writing/one/lists-and-tables#create_useful_tables) +information. [Mermaid](https://github.blog/developer-skills/github/include-diagrams-markdown-files-mermaid/) +allows diagrams to be represented in Markdown and provides support for a variety of common diagram formats such as flow +charts and UML. ## README Template From 8cbe044c4d5ed8b3f523a17df4b3c9924d403b0f Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Thu, 5 Feb 2026 09:23:15 +0000 Subject: [PATCH 16/18] Renames repo-documentation -> documentation --- repo-documentation.md => documentation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) rename repo-documentation.md => documentation.md (97%) diff --git a/repo-documentation.md b/documentation.md similarity index 97% rename from repo-documentation.md rename to documentation.md index 10a7ad8..db8ba2e 100644 --- a/repo-documentation.md +++ b/documentation.md @@ -1,7 +1,6 @@ -# Repo Documentation +# Documentation -Repositories are often the first place an engineer will look for documentation on a project. Effective technical -documentation is a gift to your future self, and will save you and others time. +Effective technical documentation is a gift to your future self, and will save you and others time. This document provides practical advice on writing high quality technical documentation with a recommended structure for the base README file of a repo. From df53aa56e02c0b96384b30a628057a0fd868e71f Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Thu, 5 Feb 2026 09:45:17 +0000 Subject: [PATCH 17/18] Improve markdown template top-level description advice --- documentation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation.md b/documentation.md index db8ba2e..b4fb910 100644 --- a/documentation.md +++ b/documentation.md @@ -128,7 +128,9 @@ template is not intended to replace all other documentation but rather provide a ## Contents From 8c02185546cdc1f8678d96971ed8246ca0dbbab5 Mon Sep 17 00:00:00 2001 From: Sam Hession Date: Thu, 5 Feb 2026 09:57:05 +0000 Subject: [PATCH 18/18] Improve README template introduction advice --- documentation.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/documentation.md b/documentation.md index b4fb910..02e1116 100644 --- a/documentation.md +++ b/documentation.md @@ -144,13 +144,14 @@ see. As such, this description should be carefully considered. ## 1. Introduction