Automagic reflection for documentation patches

[sebescudie]

bon matin!

when documenting a large library, often comes the need to create reference patches that give “cold and austere” information about a node (kinda like this in the old days). this is what we did with Elementa, where you have some sort of “encyclopedia articles” for each widget (not sure why we labelled those HowTo rather than Reference back then…) :

usually, you’d want the following things :

• display the node’s description/remarks/warnings in a text comment
• display the pin’s descriptions next to them
• show a node with all its IOBoxes created and gracefully aligned with their pins

and doing that is a pain right now because :

• you have to CTRL+M inside the node to manually copy those descriptions/remarks and paste them in the patch one by one
• if you make a change to a description (be it a node or a pin), you potentially have to manually update it in all help patches
• if you add a pin to a node later, you might break the aesthetic beauty of your patch because the IOBoxes would not be aligned then (and in fact you’d have to reorder/realign them by hand, copy and paste the new pin description, etc)

so, I was thinking about this :

• is there a way we could have some smart IOBoxes that would “know” that they’re in the help patch of that particular node, and have to display the content of its Description? maybe by setting some sort of tag on them, like we have in beta? those smart IOBoxes could either display the description or remarks, which would allow to put them in distinct comment ioboxes/regions. this way, we would just have to edit a node’s description in CTRL+M and it would automagically reflect in the patch (after a vvvv reboot I guess)

• could we have something like an “expose pins” (maybe not the right term!) button on a node’s right-click that would create those beautifully aligned links?

• could we also have those smart IOBoxes that would also display a pin’s description?

the idea of course is not to strictly automate and freeze everything : for example, instead of just displaying a pin’s description, you might want to add a small remark, or give more in depth information. it’s just about gaining ease of use in the process of creating that kind of repetitive documentation.

if you have more/different ideas about that topic, please bring’em and let’s discuss it :)

merci,

seb

[everyoneishappy]

+1000.
Streamlining this to what ever extent is realistic would be very encouraging for making better and more comprehensive documentations. Producing extensive reference material is very daunting in the current context @sebescudie is describing.

[SuperflysiNZ]

This would be amazing.

[tonfilm]

@sebescudie

if you have more/different ideas about that topic, please bring’em and let’s discuss it :)

and definitely, a build step that checks for updated documentation and displays a warning or even automatically copies the new/changed information.

[joreg]

just to briefly confirm that this aligns with our thinking. we’ll come back to this thread once we’re working on this.

[sebescudie]

thanks for the feedback!

just adding something else here to collect thoughts about documentation without creating another post (just adding it here because i thought about this while editing a help patch, not to insist/pressure or something) : we could have the same kind of smart IOBoxes that link to other help patches.

for instance, I might want to link people to Fuse’s introduction SDF patch from inside a Material help patch, and that smart IOBox should be able to display the correct patch name even if we change it later, and maybe show up as red if the help patch gets deleted for some reason (which could also raise an error when checking help patches with VS tests)