Guideline against "pseudo modules" is problematic

[stoobie]

The guide says:

NOTE The following standard is recommended when the documentation is being maintained without a Content Management System (CMS) capable of managing complex interrelations between modules. The use of reusable text snippet files (or text fragment files) is discouraged due to the complications that can arise due to the complexity they introduce.

Snippet (fragment) file use should be limited to:

• Standardized admonitions (such as 'Technology preview' and 'Beta' text).
• Where there is an existing standard between the upstream and downstream communities.

This needs either to be rethought or requires a better explanation.

I think that this guideline is not realistic. When you duplicate the same text in many places, you introduce opportunities for bugs that you can't catch easily. We don't have a CMS, but I have encountered more errors introduced because of needing to manually manage duplicate text than I have because of reusing snippets in our doc repo. I wonder if whoever wrote this made global assumptions about the way that repos are managed, assumptions which perhaps do not apply to all cases.

[pwright]

One way to think about this is that for upstream you can do anything you want, as long as you produce compliant adoc files for downstream. eg:

• use https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb to create the 'combined' adoc
• use https://github.com/fbolton/nebel to achieve the same result

The disadvantage of this thought experiment is that the module is no longer the 'thing you edit' to make changes.

[sterobin]

@pwright , great point. And once we have a finished proof of concept available for the asciidoc splitter for Kogito and Quarkus docs, which generates module files for the exact purpose of extracting the FCC structure from communities, I'll be opening up that discussion more for greater CCS adoption for anyone else interested. I essentially makes modules-as-separate-files something we don't do explicitly. I've created an example source repo and example generated repo as the basis, in a way that could be more widely adopted for those interested. I discuss these as part of my FCC repo workshop that I give monthly, and am also working on getting some feedback from the FCC group to use the generated repo structure as one of the suggested structure options for those who would like it, regardless of the splitter. We'll see.

@stoobie , way off base now, sorry, but I give a +1 and suggest that we say to use snippet includes judiciously, but not to discourage them per se. I think this was just wording to emphasize that exact sentiment, so it didn't get out of hand.

[jamsmithredhat]

++1 on don't hate the snippet :)

On Thu, May 28, 2020 at 9:01 AM Stetson Robinson notifications@github.com wrote:

@pwright https://github.com/pwright , great point. And once we have a finished proof of concept available for the asciidoc splitter https://github.com/LightGuard/asciidoc-splitter for Kogito and Quarkus docs, which generates module files for the exact purpose of extracting the FCC structure from communities, I'll be opening up that discussion more for greater CCS adoption for anyone else interested. I essentially makes modules-as-separate-files something we don't do explicitly. I've created an example source repo https://github.com/sterobin/kie-docs/tree/master-kogito-test-source-B and example generated repo https://github.com/sterobin/kie-docs/tree/master-kogito-test-split-B as the basis, in a way that could be more widely adopted for those interested. I discuss these as part of my FCC repo workshop that I give monthly, and am also working on getting some feedback from the FCC group to use the generated repo structure as one of the suggested structure options for those who would like it, regardless of the splitter. We'll see.

@stoobie https://github.com/stoobie , way off base now, sorry, but I give a +1 and suggest that we say to use snippet includes judiciously, but not to discourage them per se. I think this was just wording to emphasize that exact sentiment, so it didn't get out of hand.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/redhat-documentation/modular-docs/issues/116#issuecomment-635335485, or unsubscribe https://github.com/notifications/unsubscribe-auth/AKBSVSW72LOWUSB4FUORQ4TRTZODZANCNFSM4M7O3Y6Q .

--

James Smith

Senior Technical Writer

M: 1-504-432-9756 IM: jamsmith https://red.ht/sig

[theashiot]

+1 @stoobie

Perhaps what we can do is to create guidelines for using snippets. In addition to the existing text, we can enhance the section as:

Use reusable text snippet files (or text fragment files) only for the following:
- Standardized admonitions (such as 'Technology preview' and 'Beta' text).
- Where there is an existing standard between the upstream and downstream
  communities.
- Any content that is used without modification across modules and where any 
  change to the text must necessarily hold true for each module that includes it.

Follow these rules when creating text snippet files:
- Store the snippets in the directory that contains static resources such as the 
  _artifatcs directory. 
- Ensure that when you include text snippets in a module, you do not make the 
  module source difficult to follow.

We can compile a list of such rules and guidelines and update the section. What to you think @stoobie ?

best, ashwin

[stoobie]

+1 @theashiot As far as I can see, you covered it!

[stoobie]

@pwright

The disadvantage of this thought experiment is that the module is no longer the 'thing you edit' to make changes. I see your point, but I'm not sure that this is the ultimate goal. I think the ultimate goal is the least complex and least bug-prone source. Admittedly, snippets add complexity, but for me, they reduce how bug-prone the content is. Duplicate text across many files...does that add complexity or not? I'm not sure, but I am sure that it's a great way to introduce bugs and require more labor.

@sterobin I have to admit that I'm a bit lost regarding what your goal is with the asciidoc splitter...

[sterobin]

@stoobie , disregard the splitter-related bit, which is highly experimental at the moment and was just related to something Paul and I had previously discussed.

Bottom line, +1 for snippets. I hadn't thought about where they'd live. I suppose within the artifacts folder where attributes are maintained is fine, as people here seem to be suggesting. Seems like it belongs somewhere else, maybe it's own snippets folder at the same level as modules and assemblies, but I really can't say, so going with the majority rule on that for now.

[emmurphy1]

@theashiot we really need to talk to the Pantheon tooling group to see what is possible from their POV. I think they are open to it, but it's a crucial part of any changes or recommendations we make.

[theashiot]

Understood @emmurphy1.

[stoobie]

@benradey Remind me: Does Pantheon 2 currently not allow modules to include other modules?

[benradey]

@stoobie That's right, "modules including modules" has always been disallowed.

Modules CAN include Resources, which are tiny pieces of content that cannot be published standalone. That might fit the bill for what you're talking about here (I skimmed the conversation so there may be finer points that I have missed).

[theashiot]

Hi @benradey,

The current guide says:

The use of reusable text snippet files (or text fragment files) is discouraged due to the complications that can arise due to the complexity they introduce.

Snippet (fragment) file use should be limited to:

Standardized admonitions (such as 'Technology preview' and 'Beta' text).

Where there is an existing standard between the upstream and downstream communities.

Ref: https://redhat-documentation.github.io/modular-docs/#using_text_snippets_or_text_fragments_{context}

Would it be correct to add the following to what is permissible to be used as snippets:

Any content that is used without modification across modules and where any change to the text must necessarily hold true for each module that includes it.

Follow these rules when creating text snippet files:

• Store the snippets in the directory that contains static resources such as the _artifatcs directory.
• Ensure that when you include text snippets in a module, you do not make the module source difficult to follow.

best, ashwin

[benradey]

@theashiot I don't have a problem with any of that!

[emmurphy1]

@theashiot I think we are getting close. We need to make a very clear distinction between modules and snippets. A module is an asciidoc file that includes the elements of a concept, reference, procedure, or assembly template. A module cannot include another module but a module can include a snippet. I think to say a snippet is 'any content that is used without modification' is too broad. Modules can fit that description. So what are the defining characteristics of a snippet?
What is too large? What is too small? For example, do we want to allow a single step as a snippet of is that too granular? When is a snippet too large? What elements can a snippet contain? Is snippet the best term? Can multiple steps of a procedure be a snippet (without the rest of the procedure module template elements)? Can a table be a snippet?

I think it is important to explore these questions so that we can provide clear guidelines. We have seen that because of the flexibility of the modular documentation module when guidelines are not clear or specific consistency issues occur.

[ncbaratta]

For my part, the length isn't a factor in snippets. I create snippets when something is repeated in multiple modules so that I only have to update it in one place. So, for example, in OpenJDK we have a snippet with 3 procedural steps that we can put in anywhere and include in multiple modules. On other projects, I have snippets that include a few paragraphs of a concept (OpenJDK example).

[inoxx03]

I think having a snippet module type is generally useful in our modular docs structure. As to what content constitutes a snippet, I think that should be mainly content (of any length) that is often repeated throughout a documentation set. Most notable examples might include Technology preview notes, Deprecation notices, notes about the availability (or lack thereof) of particular components or features on specific platforms or architectures, etc. Short procedures, such as the one in the example by @ncbaratta are also good content to be made into snippets. One potential unifying feature that I can think of is that the snippet content has to be general enough not to require modification despite repeated reuse (that is, it is not too heavy on references to specific products, versions and/or component or subsystem names). Some deviation from these guidelines should be permitted, but not as much as to allow an Everything is a Snippet type of situation.

Regarding the designation and storage of such snippets, when we do recognize them as a formal content type, we should assign them a prefix (something like snip could work), and determine where they should be stored. Per the suggestion by @sterobin, we can initially store snippets in the same directory that contains a project's attribute files. Ultimately, we should collaborate with the Customer Portal engineering team to make the snippets reusable across products.

DISCALIMER: some of the info herein might be redundant, but my aim is to capture what was discussed at the meeting :)

[emmurphy1]

@adahms this issue has been resolved and merged.