Skip to content

update-docs.md

Latest commit

 

History

History
108 lines (80 loc) · 3.56 KB

update-docs.md

File metadata and controls

108 lines (80 loc) · 3.56 KB
Raw
name update-docs
description Update or add a documentation page under docs/content/ (Hugo static site).
when_to_use User asks to "update the docs", "add a doc page", "fix the documentation", or changes a feature whose page is published at https://microsoft.github.io/AI-Engineering-Coach/.

Update Docs

The published docs at https://microsoft.github.io/AI-Engineering-Coach/ are built from docs/ with Hugo. Each page is a markdown file with YAML front matter; section landing pages are _index.md.

Layout

docs/
├── hugo.toml                      # site config
├── AUTHORING_RULES.md             # rule and metric authoring guide (separate doc, not Hugo)
├── content/
│   ├── _index.md                  # site home
│   ├── features/_index.md
│   ├── getting-started/{installation,supported-tools}.md
│   ├── improve/{anti-patterns,context-health,data-explorer,
│   │            rule-editor,rule-playground,skill-finder}.md
│   ├── level-up/{achievements,learning,sdlc,share}.md
│   ├── measure/{burndown,output,patterns}.md
│   └── observe/{dashboard,timeline}.md
└── themes/                        # Hugo theme; do not edit

The page URL maps from the file path: docs/content/improve/skill-finder.md → /improve/skill-finder/.

Front matter

Every content page starts with:

---
title: "Skill Finder"
weight: 20            # ordering inside the section
description: "One-line summary used in section listings"
---

Section index files (_index.md) use the same front matter; their weight orders the section in the top-level nav.

Internal links

Inside docs/content/, link to other pages by their site path:

See the [Rule Editor](/improve/rule-editor/) for live-test details.

Outside docs/content/ — including from AGENTS.md, README.md, or CONTRIBUTING.md — these site paths do not resolve on GitHub. Use a repo-relative path instead:

See [docs/content/improve/rule-editor.md](docs/content/improve/rule-editor.md).

Screenshots

  • Drop the image at docs/static/screenshots/<slug>.png. Hugo serves it at /screenshots/<slug>.png.

  • Reuse an existing dashboard screenshot from assets/ only if it already shows the page; do not copy assets into docs/static/ to avoid drift.

  • Reference inside a doc page:

    ![Skill Finder](/screenshots/screen-skill-finder.png)

Local preview

Hugo is not pinned in this repo. Install it locally (brew install hugo / go install github.com/gohugoio/hugo@latest) then:

cd docs
hugo server -D

The PDF build (docs/build-pdf.sh) is optional; CI doesn't require it for a docs PR.

Cross-references to update

When you add or rename a page, also update:

  • AGENTS.md Documentation Index at the repo root.
  • The section's _index.md bullet list (e.g. docs/content/improve/_index.md).
  • Any sibling pages that link to the renamed page.
  • README.md "Pages" tables if the change affects feature framing.

Spellcheck

npm run spellcheck runs cspell over docs/**/*.md. Add genuine new terms (product names, acronyms) to cspell.json — do not silence the check inline.

Anti-patterns

  • Don't add a doc page without an entry in the section's _index.md — the nav skips it.
  • Don't link to https://microsoft.github.io/AI-Engineering-Coach/... from within docs/content/ pages; use the relative site path so local preview works too.
  • Don't write content that duplicates README.md — link to the doc page from the README instead.