◊(Local Yarn Code "Tech-note a0c8ebab")

Tech-note [1249a772] at [2019-02-10 04:28:46] entered by user joel on [2019-02-19 17:46:26]:

Scribble docs and Fossil integration

The next thing I need to tackle, really, is ticket [3514e65] — Series pages.

However, I’ve been away from the source code for a bit and find myself needing a refresher before I do that one.

So I’ve decided to focus on another task: building the Scribble documentation for the code I’ve written so far. This is a great fit for where I’m at now, because it can be done in small spurts, it’s rewarding because it looks cool, and it serves as a much-needed bank of cognitive effort that will pay off as I build on the foundation I started and things get a bit more complicated.

Scribble is the best code documentation system I have yet seen. It cross-references everything to everything, its structural demands expose gaps in your design and thinking while you’re writing it, and it just plain looks good. (When I reskinned this repo my goal was to get it visually in line with the styles used by the Scribble documents I knew would be coming later.)

You can see this evolving in real time in the Code Docs section of this repo. As I edit the Scribble docs in the code-docs folder, I update the HTML output live on this site pretty much continuously so I can check my work. To reduce timeline churn, I only check in the changes to the original .scrbl files themselves in very large hunks.

I’ve never seen Fossil and Scribble integrated anywhere else, but they go together very well. If you specifically want to understand that integration, here's what to look at:

If, despite your interest in this topic, these pointers still seem a little inscrutable, just go out and try setting up a Fossil repo and with integrated Scribble docs like this one. You’ll run into obstacles. Then the stuff above will make a lot more sense.