Software Engineering Metrics

About this project

Project documentation for the book: how it is put together, how to build and check it, and where the source of truth lives. For the book itself, see the table of contents.

Map of the project

  • The book: published in four locales under locales/; see spec/locales.md. This locale, en-gb-oxendict/topics/ (63 files), en-gb-oxendict/front-matter/, and the appendices in Part 9 are the hand-authored source; en-001, en-gb, and en-us are derived from it.
  • Source of truth: spec/ at the repository root (not published to the site). The structure is declared in spec/structure.md, the writing rules in spec/conventions.md, and the spelling in spec/oxford-spelling.md. Everything else is built to match.
  • Tooling: tools/localize.py derives the other three locales; tools/gen_nav.py generates navigation; tests/validate.py enforces the spec; the justfile wires them together.
  • Contributor guidance: AGENTS.md at the repository root, and the guides in the contributing section.

Build and check

The validation suite runs on Python 3 with no other dependencies and no network access. Tasks run through just.

just test    # validate structure, style, links, and spec-vs-disk
just nav     # regenerate the generated navigation files
just check   # nav, then test
just stats   # topic and word counts

This repository holds the book’s content and specification. It is rendered into a website by the separate software-engineering-metrics.github.io repository.

How specification-driven development works here

The specification comes first. spec/structure.md says which topics exist and how they are numbered. spec/conventions.md says how they must be written. The topics are authored to satisfy both. tools/gen_nav.py derives the navigation from the topics, and tests/validate.py checks the result back against the spec. If the topics and the spec ever disagree, the tests fail, which is the signal to bring them back into line.

This keeps drift out: a change is only “done” when the spec, the topics, the generated navigation, and the tests all agree.

Design decisions worth knowing

  • Flat, decimal-numbered topics. Files are locales/<locale>/topics/PP-CC-slug.md, the same slug in every locale. The part is a whole number; the topic is a decimal; N.0 is the part introduction. This keeps stable identifiers and lets tools sort and group without a directory tree.
  • One hand-authored locale, three derived. en-gb-oxendict is Oxford spelling, the house style of most international standards bodies (see spec/oxford-spelling.md); en-001, en-gb, and en-us are mechanically derived from it, so translation never drifts from the source.
  • Generated navigation. The table of contents, contents page, and subject index are generated, so they never drift from the topics.
  • Offline, dependency-free tests. The suite uses only the standard library so it runs anywhere, including CI and pre-commit hooks.
  • Cross-references stay plain text. Prose refers to topics by decimal number (“see topic 2.1”), as the spec requires; the rendering site is responsible for turning those references into links.
  • No em-dashes, by rule and by test. A deliberate style choice, enforced so it stays true as the book grows.
  • Every metric family names its own gaming vector. This is the one rule in the template that has no equivalent in the sibling software-engineering-guide project: it exists because this book’s whole subject is measurement, so the risk of measurement itself has to be first-class, not implicit.

Further reading

  • Authoring : writing and editing topics.
  • Navigation : how the generated files work.
  • Testing : what the tests check and how to fix failures.
  • Examples : small, concrete examples.
  • Changelog : history of notable changes.