Add infrastructure for keeping design documents #6

New issue

Open

opened 2025-10-03 23:06:31 +02:00 by federico · 1 comment

federico commented

2025-10-03 23:06:31 +02:00

Collaborator

Examples from other projects:

The idea is to write informal descriptions of big features or big changes to be done to the software, and to use them as brainstorming tools. They later serve as a history of the software's development decisions.

Both of those examples are embedded in a general development guide for each of librsvg/gnome-crosswords. It's not documentation for users of the project, but documentation for its developers. I've found it very useful to put stuff there like the internal API reference, a description of the CI, detailed compilation instructions, how to set up a development environment, etc.

Questions for @ro:

What documentation system would you prefer? librsvg's uses Sphinx with .rst files; Crosswords uses Sphinx with .md files. Both work fine.
If you want to keep this a Rust-aligned shop, mdbook works very well; it renders books with Markdown (a lot of Rust documentation is rendered with it).

The cheap, do-nothing alternative is just to throw .md files in a devel-docs directory, too.

I can put either of those in the CI if you want.

Examples from other projects: * [Design documents in librsvg](https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/#design-documents) * [Design documents in GNOME Crosswords](https://jrb.pages.gitlab.gnome.org/crosswords/devel-docs/designs/index.html) The idea is to write informal descriptions of big features or big changes to be done to the software, and to use them as brainstorming tools. They later serve as a history of the software's development decisions. Both of those examples are embedded in a general development guide for each of librsvg/gnome-crosswords. It's not documentation for users of the project, but documentation for its developers. I've found it very useful to put stuff there like the internal API reference, a description of the CI, detailed compilation instructions, how to set up a development environment, etc. Questions for @ro: * What documentation system would you prefer? librsvg's uses Sphinx with .rst files; Crosswords uses Sphinx with .md files. Both work fine. * If you want to keep this a Rust-aligned shop, [`mdbook`](https://rust-lang.github.io/mdBook/) works very well; it renders books with Markdown (a lot of Rust documentation is rendered with it). The cheap, do-nothing alternative is just to throw .md files in a `devel-docs` directory, too. I can put either of those in the CI if you want.