Regarding documentation experiences, recently I describe my
approach on them [1], also using a moldable tool I create for that
specific purpose. It could be helpful to you.
Thanks for this link. Grafoscopio looks really cool. I'm generally really happy to see another application using the moldable tools approach.
I have settled on an initial documentation strategy for now. On one side it's really simple: I write the manual in markdown and format it with pandoc. On the other side it's a bit fancer: the CI builds the manual and automatically generates screenshots for each of the visualizations. Hopefully it will be a nice kind of "WYSIWYG" to know that the code and documentation are always exactly synchronized.
Here is my early first draft, with the automatically generated screenshots being at the bottom:
I'm using Nix to build the screenshots. This way it can easily download and run some complex software dependencies (a JIT compiler) to generate the example data to source into the screenshots. Looks like this if anybody is curious:
One challenge you can see here is that I am trying to explain the Glamorous Toolkit interface from first principles. Is there a better approach? I worry that linking to the homepage will be a bit confusing because there is so much Smalltalk there and also the docs seem a bit fragmented between small blog entries and videos. I'll see how it goes as I start onboarding my initial users anyway.