Skip to content

Issue #116: Guideline against "pseudo modules" is problematic #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Issue #116: Guideline against "pseudo modules" is problematic #123

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,16 @@
[NOTE]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's decide what to call these - snippets or fragment, then change the title to one or the other (Text snippets for example). Then add a definition at the start of the module:

A text snippet is text that is stored in an asciidoc file that you can include in a module. Text snippets usually contain text that is repeated in more than one module. Using a text snippet insures consistency across modules. Text snippets can be used for the following types of information:

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I vote for snippets! Is there any argument for fragment?

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:
Use reusable text snippet files (or text fragment files) only for the following:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we really need to limit text snippets to these examples?


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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would this be, specifically?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Where there is an existing standard between the upstream and downstream communities." clause also comes from the original text. I can find out what the specifics were.

* Any content that is used without modification across modules. Ensure that any change to this content must necessarily hold true for each module that includes it.

Follow these rules when creating text snippet files:

* Store the text snippet files in a directory that contains static resources. For example, the `_artifatcs` directory.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Store the text snippet files in a directory that contains static resources. For example, the `_artifatcs` directory.
* Store the text snippet files in a directory that contains static resources. For example, the `_artifacts` directory.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, updated.

* Ensure that when you include text snippet files in a module, you do not make the module source difficult to follow.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So here, by module do you mean the snippet? Suggestion:
Ensure that the path to the text snippet is not difficult to follow.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps I can explain this a little more. My concern is that we should not end up with a module that looks like this:

= Hello world

include::_artifacts/common-intro.adoc[]

Some content here.


include::_artifact/list-of-commands.adoc[]

what do you think?


//.Additional resources

Expand Down