When I started helping out with Crosswords, JRB taught me a valuable lesson: before implementing a non-trivial feature, or doing a non-trivial change, one should first write a document with the design of the feature. It doesn't have to be anything formal; just an explanation of where you are coming from, the point to which you want to get, and a little technical detail if appropriate. You can then discuss the feature based on the document itself before going down the rabbit hole of actually implementing it.
Over time, these little documents form a high-level technical overview of the thing you are building; a sort of development history with less irrelevant detail than commit logs.
You can see examples of these little documents in the repository for Crosswords.
I started to do this for the things I wanted to implement in Crosswords, but then in librsvg as well and later in at-spi2-core, too. Normally I keep unpublished documents with lots of personal notes on things I want to implement; JRB's tip gave me an excuse to actually make them readable and publish them.
While I was documenting the initial CI for at-spi2-core, and while looking for resources on code coverage setups, I ran into the Firefox Source Tree Documentation and also the Guide to Rustc Development. Both have tours of sections of their respective code bases, they document development procedures — that sort of thing. Perfect!
May I present to you:
Both documents are generated from text files in their respective repositories. The rendered documents get published from the CI pipeline, at the same time as the API reference guides. Hopefully the documents can be kept up to date right there as one works on the code, instead of being written once and then rotting in a wiki.
This is already yielding fruit. My Outreachy intern for the December 2022 round was able to get started with librsvg's development and I didn't even have to tell them how to get started, because the development guide has a section on setting up a development environment. The Outreachy project for performance tracking in librsvg is also detailed there. The guide for at-spi2-core gives me a place to link to obscure knowledge, as well as to keep reference material for ourselves.
Technical details: both documents are in reStructuredText, and processed with Sphinx, as that seemed well-maintained enough. Using something like mdbook would also work fine.
I am not as comfortable with reStructuredText and Sphinx as I am with Markdown, so if anyone has tips for how to make the docs look prettier (in particular, the table of contents in at-spi2-core's guide is terrible), I'd appreciate your comments!
I also have to actually go and turn the Crosswords documents into a book.
(Remember Code Hospitality? Yeah, exactly that.)