issue 175 - adding an assembly attribute by kalexand-rh · Pull Request #176 · redhat-documentation/modular-docs (original) (raw)
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.
By clicking “Sign up for GitHub”, you agree to our terms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Conversation6 Commits2 Checks0 Files changed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
[ Show hidden characters]({{ revealButtonHref }})
Updated #175 to summarize the proposal.
| @@ -13,6 +13,14 @@ NOTE: A text snippet is not a module. |
|---|
| . Create the text snippet AsciiDoc file. |
| + |
| NOTE: Consider storing snippet files in a separate snippets folder. |
| . Add a variable to the snippet files that that identifies its content type: |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @kalexand-rh . Just a couple minor comments.
| @@ -27,13 +27,14 @@ Create assembly and module file names that accurately and closely reflect the ti |
|---|
| Do not include special characters in file names. Ensure that all members of your team use the same file naming conventions. |
| ==== |
| These file naming guidelines are optional but highly recommended. However, if your team does not include the module prefixes in file names followed by either a hyphen (-) or an underscore (_), include one of the following variables in each concept, procedure, and reference module before the module ID: |
| These file naming guidelines are optional but highly recommended. However, if your team does not include the module prefixes in file names followed by either a hyphen (-) or an underscore (_), include one of the following variables in each assembly file and concept, procedure, and reference module before the module ID: |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| These file naming guidelines are optional but highly recommended. However, if your team does not include the module prefixes in file names followed by either a hyphen (-) or an underscore (_), include one of the following variables in each assembly file and concept, procedure, and reference module before the module ID: |
|---|
| These file naming guidelines are optional but highly recommended. However, if your team does not include the prefixes in file names followed by either a hyphen (-) or an underscore (_), include one of the following variables in each file before the anchor ID: |
| :_content-type: ASSEMBLY |
|---|
| :_content-type: CONCEPT |
| :_content-type: PROCEDURE |
| :_content-type: REFERENCE |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just a side note that I think is outside of the scope of this PR. We might want to update the intro section to this chap to also mention snippets, and include a snippet file in the example file names previously in this section, and then add a content-type of SNIPPET to this list. But snippets are still fairly new territory, so not sure if we're to a point that we want to mention it beyond the snippets section later in this guide, which you've correctly updated. So I think good for now unless someone wants to expand this section to include snippets in a separate PR.
In mod doc review board meeting Dec 8, 2021, decided to freeze this PR until the dust settles with Jupiter post-Summit to ensure that the requirements don't again change, and also to see at that point if we can get a concrete answer on how the distinction of content and even module type has actual customer value beyond just a new tooling requirement. To be discussed post-Summit.
Labels
for discussion topics that may later become enhancements