Diagrams in "Nested assemblies" section are outdated

[sterobin]

As I mentioned in PR #106 and issue #107 , the two diagrams in the nesting assemblies section of the mod doc ref guide are outdated - they use the old parent context method instead of the new ifdef parent context method, described in the doc and in the templates. I could replace them myself with whatever, but does anyone know who originally did those and all diagrams in the ref guide? They could likely more easily make the update and keep things looking consistent.

@adahms @ritz303 @rkratky ? ^^

[IngridT1]

I think @rkratky or @asteflova created these. Aneta is on maternity leave, but Robert probably knows where the diagrams are.

[rolfedh]

@rkratky Do you know where the source files for the above-referenced diagrams might be?

[thatdocslady]

Looking at the current topic, this looks like it was fixed to reflect the ifdef context method:

https://redhat-documentation.github.io/modular-docs/#nesting-assemblies

Recommending to close this issue as resolved.

[sterobin]

@thatdocslady Thanks for looking into this! So the issue is still there. The diagram shows the old parent-context method without the ifdefs. Note the instruction in the doc (correct) right before the diagram (which is incorrect). It's illustrated correctly in the assembly template, just that diagram is outdated. I opened this issue in hopes that whoever created the diagram could very quick update the source. But no such luck. So we might need to re-create the diagram, which would likely mean re-creating the other for consistency. That's kind of why this has sat here for so long.

[thatdocslady]

@sterobin hmmm from what I saw in the topic, the first diagram (Example 4) illustrates how "not to do this", and the subsequent text shows the ifdef method on how to fix things. Is it possible that the diagram that you're referring to is Example 5? If yes, then I stand corrected :)

Maybe we can rework the topic to avoid diagrams by replacing them with code blocks? Similar to product docs, it seems that maintaining diagrams here is also a bit of a PITA, and the code blocks can be copied out of the templates or even dynamically produced from the templates if we want to get fancy!

[sterobin]

@thatdocslady Sorry, let me clarify. This issue is raised because both Example 4 and Example 5 are outdated, each for different reasons.

Example 4 is outdated because it doesn't use the correct tag for the additional resources (which should be the role_ tag instead of the standard anchor ID). No biggie, but still a point of confusion.

Example 5 is outdated it's using the wrong (old) parent-context approach instead of the correct ifdef approach described in the text right before it.

The correct method for Example 5 is to enclose as follows, as explained in the text and in the assembly templates:

Correct notation, needed in Example 5

ifdef::context[:parent-context: {context}]
...
ifdef::parent-context[:context: {parent-context}]
ifndef::parent-context[:!context:]

Incorrect notation currently shown in Example 5

:parent-context: {context}
...
:context: {parent-context}

And you're totally right that a very easy alternative would be to ditch the diagrams and to just show a code block of an example nested assembly structure with all the correct notations, easily maintainable. But I think when I brought this up, there was a strong preference in the group for diagrams to help illustrate, since the assembly template itself already kind of provides the non-diagrammatic example.

That said, clearly we can't seem to maintain diagrams with any kind of reasonable turnaround, as proven by this issue. It was supposed to be very easy if someone could just provide the source to the images that I could update. It would be super easy for me to just re-create the diagrams, no prob, but then they'd be an inconsistent look compared to the others throughout the doc.

Let me try once more to hunt down @rkratky and @asteflova to see if one of them still has the diagram source files and if they can include those in the repo to avoid this issue in the future. Will get back to you.

[rkratky]

Suggestion: use Asciidoctor Diagram to have the graphics generated automatically at build time. This would eliminate the need for someone to draw, convert, and upload the images manually.

https://asciidoctor.org/docs/asciidoctor-diagram/

[sterobin]

Thanks @rkratky . Have found the search for the png source files to be in vain, so giving up and pursuing another route to just re-create the diagrams in a way that's more maintainable, such as what Robert suggests.

I've assigned this to me to carry it through. Will address just these two diagrams for now, propose to the board, and if all are agreed, then will consider another issue to treat all other images likewise for consistency.

Thanks @thatdocslady again for resurfacing this!

[sterobin]

Addressed in PR #168 . I ended up foregoing the Asciidoctor Diagram option because it was proving to be too cumbersome and limited, also unattractive. I instead just designed a simple diagram illustration in LibreOffice and included both the ODT source files and the final PNG files in the repo, so we don't run into this issue again.