WIP: issue-116-emily #116: Guideline against "pseudo modules" is problematic #161
Conversation
emmurphy1
changed the title
modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc
Outdated
Show resolved
Hide resolved
modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc
Outdated
Show resolved
Hide resolved
modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc
Outdated
Show resolved
Hide resolved
modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc
Outdated
Show resolved
Hide resolved
modular-docs-manual/content/topics/module_what-modular-documentation-is.adoc
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
@emmurphy1 I agree with Mike's and Nicole's existing comments and have added my +1s where applicable. Once those are addressed, good with me.
modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc
Outdated
Show resolved
Hide resolved
|
|
||
| //* A bulleted list of links to other material closely related to the contents of the concept module. | ||
| .Procedure | ||
| . Create the text snippet Asciidoc file and store it in your snippets folder. |
There was a problem hiding this comment.
I'll lick a fingertip and then reach out for the third rail...vanilla Asciidoctor is perfectly happy with a snippets folder. Does the tooling that we're not supposed to be overly focused on also support a snippets folder?
Other than mental harm, is it problematic to put the text frags in a modules folder?--I get it that we just stated it's not a module, then we're possibly advising to co-locate with the modules.
There was a problem hiding this comment.
Yes, the Publishing-Platform-That-Shall-Not-Be-Named needs to have fragments in a single location. This location is added to the YAML file.
There was a problem hiding this comment.
I'd swear that the file now includes mention of a "fragments" folder, but I did not checkout the PR. I share that in case it was an overzealous change from "snippets" to "fragments." I'm good with whatever you propose.
There was a problem hiding this comment.
Well, I was trying to be consistent.
|
@mikemckiernan and @ncbaratta I have updated with your comments, or explained. Please review when you have time. |
|
|
||
| = Text Fragments | ||
|
|
||
| A text fragment is a small section of text that is stored in an Asciidoc file. Text fragments contain content that is resused in multiple modules or assemblies, for example: |
There was a problem hiding this comment.
| A text fragment is a small section of text that is stored in an Asciidoc file. Text fragments contain content that is resused in multiple modules or assemblies, for example: | |
| A text fragment is a small section of text that is stored in an AsciiDoc file. Text fragments contain content that is resused in multiple modules or assemblies, for example: |
| * A step or series of steps in a procedure | ||
| * A disclaimer, for example, for technology preview or beta releases | ||
|
|
||
| NOTE: A text fragment is not a module. The Asciidoc file that contains the text fragment cannot contain any other information. A module cannot contain an include statement for another module. |
There was a problem hiding this comment.
The AsciiDoc file that contains the text fragment cannot contain any other information.
Why? AsciiDoc allows for inclusion from specific lines in another file. A common use case is to have a single file with multiple fragments/snippets. (I'm not exactly fond of snippets, but if used, then why arbitrarily restrict AsciiDoc functionality?)
| NOTE: A text fragment is not a module. The Asciidoc file that contains the text fragment cannot contain any other information. A module cannot contain an include statement for another module. | |
| NOTE: A text fragment is not a module. The AsciiDoc file that contains the text fragment cannot contain any other information. A module cannot contain an include statement for another module. |
There was a problem hiding this comment.
Good point @rkratky . Removed.
| NOTE: A text fragment is not a module. The Asciidoc file that contains the text fragment cannot contain any other information. A module cannot contain an include statement for another module. | ||
|
|
||
| .Procedure | ||
| . Create the text fragment Asciidoc file and store it in your fragments folder. |
There was a problem hiding this comment.
store it in your fragments folder
I understand that this is good practice, but do we need to call it out. In the end, it's up to the writer (or the writing team) how they wish to store their .adoc files.
| . Create the text fragment Asciidoc file and store it in your fragments folder. | |
| . Create the text fragment AsciiDoc file and store it in your fragments folder. |
There was a problem hiding this comment.
I imagine that readers will appreciate the suggested directory name and many will adopt it for the benefits of consistency. Rule breakers do whatever they want anyway.
There was a problem hiding this comment.
I made it a suggestion and put it in a note.
| * A step or series of steps in a procedure | ||
| * A disclaimer, for example, for technology preview or beta releases | ||
|
|
||
| NOTE: A text fragment is not a module. The Asciidoc file that contains the text fragment cannot contain any other information. A module cannot contain an include statement for another module. |
There was a problem hiding this comment.
A module cannot contain an include statement for another module.
Should this be: A text fragment cannot contain an include statement for another module.? That A module cannot contain an include statement for another module has been captured in the Creating modules section.
There was a problem hiding this comment.
Wow, that is a good point! I've just simplified the whole idea.
Co-authored-by: Robert Krátký <rkratky@redhat.com>
|
@rkratky @Preeticp @ncbaratta I've revised the text fragments section. Would you mind looking over again and approving if you can? |
|
@rkratky @ncbaratta @rolfedh @fbolton @fbolton @sterobin @Preeticp @mikemckiernan @yzimmerm I think I have addressed everyone's comments but there have been a few changes so would you mind looking over one last time? Also, I am now second-guessing myself and wondering if we should be talking about 'snippets' instead of 'fragments'? Ideas? |
|
It still lgtm. My preference for fragments over snippets is to sidestep possible confusion between a text file with limited text content and the feature in Atom that is named snippets and inserts small pieces of text. |
|
I've been saying 'snippets' but seriously I have no preference. |
| @@ -13,6 +13,8 @@ Follow these guidelines to create different types of modules: | |||
| * xref:creating-procedure-modules[Procedure Module] | |||
| * xref:reference-module-guidelines[Reference Module] | |||
|
|
|||
| A module should not contain another module. However a module can contain a text snippet. For information about text snippets, see xref:using-text-snippets[Using Text Snippets]. | |||
There was a problem hiding this comment.
@sterobin can you see why this xref isn't working?
There was a problem hiding this comment.
Fixed. Thanks Stetson.
This continues the work done in https://github.com/redhat-documentation/modular-docs/pull/123/files. It resolves issue 116 and issue 99.