Skip to content

Contributing to the CDS Handbook

The CDS Handbook is a shared resource, maintained collaboratively across the company. If you spot something out of date, want to add a new page, or improve existing content, this guide explains how to do it.

All changes go through a pull request (PR) review before appearing on the live site. This keeps the quality and consistency of the handbook high.

Before you start

You need:

If you cannot access the repository, speak to your line manager.

Branch naming convention

Whether you edit via the browser or locally, your branch name must follow this pattern:

contrib/<your-name>/<brief-description>

Keep the description short (2–4 words, hyphen-separated) and descriptive of your change.

Examples:

Who Change Branch name
Sarah Jones Adding a security tools page contrib/sarah-jones/add-security-tools-page
James Smith Updating the delivery approach contrib/james-smith/update-delivery-approach
Alex Taylor Fixing typos on the values page contrib/alex-taylor/fix-typos-values-page

Making changes via the browser

The simplest way to contribute — no software to install.

Editing an existing page

  1. Open the repository in ADO.

  2. Click Files in the left-hand sidebar, then navigate to the docs/ folder and find the file you want to edit.

    Tip

    Each handbook page corresponds to a .md file in docs/. For example, the Life at CDS page is docs/about/life-at-cds.md.

    The ADO Files view showing the repository structure with the docs/ folder expanded

  3. Click the file name to open it, then click the Edit (pencil) icon in the top-right corner.

    A file open in ADO with the Edit button visible in the top-right corner

  4. Make your changes in the editor. Refer to the Markdown guide below if you need help with formatting.

  5. When you are done, click Commit in the top-right corner.

  6. In the commit dialog:

    • Write a short Comment describing your change (e.g. "Update agile practices — add retrospective section")
    • Change the Branch name field from main to your new branch name, following the naming convention above
    • Tick Create a pull request
    • Click Commit

    The ADO commit dialog showing the branch name field and Create a pull request checkbox

  7. This opens the New Pull Request screen. ADO pre-fills the title and description from your commit comment — update them to be clear and descriptive:

    • Title — a concise summary of your change (e.g. "Update agile practices — add retrospective section")
    • Description — one or two sentences on what you changed and why
    • Click Create

    The New Pull Request screen showing title, description, and the Create button

Your PR will be reviewed. You will be notified when it has been approved and the changes are live.

Creating a new page

Creating a new page requires one additional step — adding it to the site navigation in mkdocs.yml. If you are editing via the browser, the reviewer will handle this before merging — mention in your PR description that a new page has been added. If you are working locally, add the page to the nav: section in mkdocs.yml yourself.

Note

The sidebar and search are auto-generated from mkdocs.yml. You do not need to add links to the page anywhere else — not to the section index page, not to the home page. One entry in mkdocs.yml is the only registration step.

  1. Open the repository and navigate to the relevant subfolder inside docs/:

    • docs/about/ — life at CDS, culture, values, behaviours, what we do
    • docs/how-we-work/ — cross-cutting approaches that apply to the whole delivery team regardless of discipline, grouped into delivery/, engineering-architecture/, and quality/. If every discipline follows it, it belongs here.
    • docs/our-people/ — the role frameworks that support CDS consultants and lead client accounts, grouped into people-support/ and account-leadership/
    • docs/practices/<name>/ — all content owned by a specific practice (engineering, QA, product delivery, ITSM): tooling, techniques, standards, and depth specific to that discipline. When in doubt, practices is the right home if it has a discipline owner.
    • docs/tools-and-tech/ — tools and technologies CDS uses, independent of a specific practice

  2. Click + New at the top-right of the file list, then select File.

    The + New dropdown in ADO showing the File and Folder options

  3. Name your file using lowercase words separated by hyphens, ending in .md — for example, my-new-page.md.

  4. Start the file with a front matter block (see Front matter and tags below), then add your content.

  5. Commit to a new branch and raise a PR as described in steps 5–7 above.

  6. In your PR description, mention that you have created a new page so the reviewer knows to add it to the navigation.

Adding images via the browser

Images must be uploaded to the repository before you can reference them in a page.

  1. Navigate to docs/assets/images/ in the ADO file browser.

  2. Click the ⋮ three-dot menu at the top-right of the file list, then select Upload file(s).

    The three-dot menu in the images folder showing the Upload file(s) option

  3. In the commit dialog, commit to the same branch you are using for your content changes — not to main.

  4. Reference the image in your Markdown file (see Images in the Markdown guide below).

Making changes locally (for developers)

If you are comfortable with Git, you can clone the repository, make changes locally, preview the site, and push a branch.

Prerequisites

  • Git
  • Python 3.10 or later and pip

Workflow

# Clone the repository (first time only)
git clone https://cdsdigital.visualstudio.com/_git/CDS%20External%20Handbook
cd "CDS External Handbook"

# Install dependencies
pip install -r requirements.txt

# Create a branch following the naming convention
git checkout -b contrib/your-name/brief-description

# Preview the site locally as you work (auto-reloads on save)
make serve

# When ready, stage and commit your changes
git add docs/your-file.md
git commit -m "Brief description of your change"

# Push your branch to ADO
git push origin contrib/your-name/brief-description

Then open ADO and raise a pull request against main.

Tip

Run make build before pushing to catch any broken links or formatting issues. The pipeline runs with --strict mode, so any warnings will fail the build.

Writing in Markdown

Handbook pages are written in Markdown — a simple formatting language that renders as styled HTML. Here is everything you need.

Headings

# Page title — use once, at the top of the page

## Major section

### Subsection

Warning

Every page should have exactly one # (H1) heading at the top. Do not skip heading levels — always H1 → H2 → H3 in order. This matters for both accessibility and search.

Text formatting

**bold text**

*italic text*

`inline code`

Lists

- Bullet point
- Another bullet point
    - Indented sub-point

1. Numbered list
2. Second item
3. Third item

[Link to an external site](https://example.com)

[Link to another handbook page](../about/our-values.md)

Use relative paths (starting with ../) to link between pages in the handbook. Do not hardcode the live site URL.

Warning

Link text must describe the destination on its own. A reader scanning links should understand where each one goes without reading the surrounding sentence. Write [See our delivery approach](...) — not [click here](...) or [read more](...).

This is an accessibility requirement (WCAG 2.4.4) and also makes content easier to scan for everyone.

Images

Images must be saved in docs/assets/images/ before you can reference them. See Adding images via the browser above for how to upload them.

Once uploaded, reference an image in your Markdown like this:

![A description of the image](../assets/images/your-image.png)

The number of ../ steps depends on where your page sits:

Page location Image path prefix
docs/your-page.md assets/images/
docs/subfolder/your-page.md ../assets/images/

Always write a meaningful description in the alt text — describe what the image shows, not just the filename or "image". This is required for accessibility (WCAG 1.1.1) and is displayed if the image fails to load. The only exception is purely decorative images that add no information — use alt="" for those.

Tables

| Column A | Column B | Column C |
|----------|----------|----------|
| Row 1    | Value    | Value    |
| Row 2    | Value    | Value    |

Code blocks

Surround code with triple backticks and specify the language for syntax highlighting:

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
make serve
```

Callout boxes

Use admonitions sparingly — only for things the reader genuinely needs to notice.

!!! tip
    A helpful suggestion.

!!! note
    Something worth knowing.

!!! warning
    Something the reader must be aware of before proceeding.

Front matter and tags

Every page must begin with a front matter block that lists relevant tags. This powers the Tags index.

---
tags:
  - how-we-work
  - agile
---

Use existing tags where possible. Common tags are: about, our-people, culture, values, behaviours, how-we-work, agile, delivery, testing, tools, devops, azure, ai, contributing, practices, engineering, product-delivery, qa, itsm.

What makes a good pull request

  • One change per PR — keep it focused. A PR that fixes a typo and rewrites a whole section is harder to review.
  • Clear title — describe what changed, not just "update page".
  • Brief description — one or two sentences on what you changed and why.
  • Check your formatting — preview your Markdown if you can, and double-check image paths and internal links.
  • Check accessibility — headings in order, descriptive link text, meaningful alt text on images. The pipeline runs automated WCAG AA checks and will block your PR if they fail.
  • New page? — if editing via the browser, mention in the description that a nav entry needs adding. If working locally, add it to mkdocs.yml yourself.