Design docs and philosophy

Pulled from a Lightning Talk Jonathan gave at GUADEC in 2024

The crosswords codebase is extensively documented — and we intend to keep it that way. Being disciplined about developer documentation pays dividends:

  • Documentation helps keep a consistent and maintainable code base

  • Thinking about a hard problem before writing code can catch problems with an approach before code reveals it

  • It’s useful to get a second pair of eyes on a problem

  • Keeping a history of design decisions is useful for reconstructing complex decisions

  • It’s much easier to refactor words than code

  • It helps new contributors to understand your code-base

And most importantly, the most important contributor to your project is future-you!! Document for that person.

Best practices

We write a design document before we write non-trivial sections of code. This is so we can discuss issues before coding, and have a big-picture development history that’s separate from the commit messages. If you’d like to extend this project in a non-trivial way, please submit a design doc MR before you begin coding. This is an MR with just a single file to be reviewed.

We use markdown with a standard template. Every doc has a header that looks something like this:

# Title
**Status**: (Draft|Approved|Deprecated|Updated) | (Optional Implemented) | (Date)

**Author**: Author Name

**Reviewer**: (Optional Reviewer Name — if someone specific should review this)

As an example,

# Editing the Acrostic Grid

**Status:** Approved | Implemented | January 2025

**Author:** Jonathan Blandford

**Reviewer:** Tanmay Patil

Please make sure to use word wrap when writing text — it makes it easier to comment on in the MR.

NOTE: Some design docs benefit from diagrams or images. This is to be encouraged. See PlayXwordColumn for an example of this.

Freshness

We revisit the docs as part of the release process:

$ emacs docs/*md

At a minimum, we update the headers to indicate if the status has changed, but we also potentially update relevant docs as well. Some designs are vital to keep accurate — such as the Word List. It’s much easier to update docs as we go along then to deal with out-of-date docs that don’t match the code.