On generating project documentation from source

[m30-jrs]

Spinning up a new thread to discuss documenting generation, as it will likely be a pretty different kind of work from management of project structure.

I have started to capture some refined thoughts about BoMs over in the Sliderule repo. I started with BoMs as I think those will be the simpler case to explore where generation is concerned. Take a look at:

• https://github.com/Mach30/sliderule/blob/master/architecture/1-behavior/core-assumptions/08-BoMs%20are%20data%20not%20documentation.adoc
• https://github.com/Mach30/sliderule/blob/master/architecture/1-behavior/use-cases/06-Generate-per-component-parts-lists-from-BoM-data.adoc
• https://github.com/Mach30/sliderule/blob/master/architecture/1-behavior/use-cases/07-Generate-project-level-purchase-list-from-BoM-data.adoc

I have not written this down elsewhere yet, but I think one of our goals with generation should be to develop something that extensible by the user, so people can add new types of data and content generation as their projects grow in scale/complexity. For example, someone might want add support to generate requirements documents from project data (maybe even us later, but it shouldn’t have to wait for us to make it possible). Or, generate operating instructions or safety materials.

But as we get started, I want to focus on implementing BoM views (see above) and assembly instructions as those are the minimum requirements to define oshw. Preferably in a way that adding support for new content generation is something that is easy for users to implement and share (with us and each other).

One last thought, as projects grow in scale, I imagine we will get to a point where we will want a build management system to figure out when generated artifacts are up to date so users don't have to waste time regenerating content unnecessarily. This also makes me think we will want a clean operation to purge all generated content.