From 1e05d2984aaf9711f51defb89e635179ff343534 Mon Sep 17 00:00:00 2001 From: Emily Murphy Date: Mon, 29 Mar 2021 14:14:06 -0400 Subject: [PATCH] issues-116 updated the text snippet section --- ...using_text_snippets_or_text_fragments.adoc | 37 +++++++------------ 1 file changed, 13 insertions(+), 24 deletions(-) diff --git a/modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc b/modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc index ae1f629..159fddc 100644 --- a/modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc +++ b/modular-docs-manual/content/topics/using_text_snippets_or_text_fragments.adoc @@ -1,30 +1,19 @@ -// Module included in the following assemblies: -// -// - -// Base the file name and the ID on the module title. For example: -// * file name: my-concept-module-a.adoc -// * ID: [id="my-concept-module-a_{context}"] -// * Title: = My concept module A - -// The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken. [id="using_text_snippets_or_text_fragments_{context}"] -// The `context` attribute enables module reuse. Every module ID includes a variable that sets the context, such as {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide. -= Text Snippets or Text Fragments (Pseudo-modules) -//In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly. -//Do not start the title of concept modules with a verb. See also _Wording of headings_ in _The IBM Style Guide_. - -[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: += Text Snippets or Text Fragments -* Standardized admonitions (such as 'Technology preview' and 'Beta' text). -* Where there is an existing standard between the upstream and downstream communities. +A text snippet or text fragment is a small section of text that is stored in an Asciidoc file. Text snippets contain context that is resused, for example: +* A step or series of steps in a procedure +* A disclaimer, for example for technology preview or beta releases -//.Additional resources +NOTE: A text snippet is not a module. The Asciidoc file that contains the text snippet cannot contain any other information. -//* 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. +. Add an include statement to the module that you want to add the snippet to, for example: ++ +[source] +---- +include::snippets/beta-note.adoc +----