Repo documentation guidance

documentation.md

@@ -0,0 +1,205 @@
+# Documentation
+
+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.
+
+## 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. 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)
+materials for improving your technical writing skills.
+
+### Write for an audience
+
+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.
+
+<!--alex ignore easy-->
+> [!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#curse_of_knowledge)
+
+
+<!--alex ignore clearly-->
+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
+
+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:
+
+> 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.
+
+– [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 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.
+
+– [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.
+
+<!--alex ignore just-->
+> [!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 [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.
+
+– [Technical Writing One / Words](https://developers.google.com/tech-writing/one/words#use_acronyms_properly)
+
+### Illustrations, lists and tables
+
+<!--alex ignore clearly-->
+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 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 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. [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
+
+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]
+
+<!--- 
+The top-level description should provide a short summary of the project, ensuring the reader is in the right place. 
+Keep this brief and provide suitable onward links, as further detail will be provided in the subsequent sections. 
+This description should consider a wider audience as it is likely to be the first piece of documentation a person may 
+see. As such, this description should be carefully considered.
+-->
+
+## 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
+
+<!--- 
+The section should provide a clear explanation for why the project exists and what it does. Different types of readers
+should be considered, including users, engineers, and managers. More specific and technical detail should be provided 
+under "How it works".
+
+Areas to include:
+ - Who are the users of this project?
+ - Why was the project made?
+ - What core features does the project provide?
+ - Which other services does it integrate with (provide links)?
+ - [When applicable] What does the project look like (include images)?
+
+-->
+
+## 2. Getting Started
+
+<!---
+This section should provide clear steps for an engineer to begin utilising or contributing to the project.
+
+This should include setup and running instructions, as well as advice for contributing to or releasing updates to the project. 
+-->
+
+## 3. How It Works
+
+<!---
+This section provides an opportunity to clarify the design of the project. It should go beyond the introduction to 
+explain the key technical aspects of the project.
+
+Areas to include:
+ - Which core technologies does the project use?
+ - What is the architecture of the project (include a diagram)?
+ - What subprojects does the project have? What do they each do?
+ - What are the key design concepts behind the project?
+ - What might surprise an engineer new to the project? 
+-->
+
+## 4. Useful Links
+
+<!---
+This section should provide helpful links to other useful resources. 
+
+These could be: 
+ - Further detailed project documentation
+        - ADRs       
+        - Runbooks
+        - Feature documentation
+        - User training
+ - Documentation of third-party libraries
+ - Other related services
+-->
+
+## 5. Terminology
+
+<!---
+This section should be linked to from previous sections and provide unambiguous definitions for the key terms 
+in the project. These are likely to be domain specific phrases which are novel to the project. They could also be phrases
+which have a specific meaning in the context of the project. If there is any doubt around a term, include it here! 
+-->
+
+```