# Design docs philosophy

*Pulled from a [Lightning
Talk](https://www.youtube.com/watch?v=0oRa8bnNUjk&t=2016s) 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](design-doc-template.md). Every doc has a header that looks
something like this:

```markdown
# 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,

```markdown
# 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.

:::{tip}
Some design docs benefit from diagrams or images. This is to be
encouraged. See
[PlayXwordColumn](/designs/crosswords-player/play-xword-column.md) for
an example.
:::

## Freshness

We revisit the docs as part of the release process.

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](/designs/shared-code/word-list.md). 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.