diff --git a/xml/MAIN.styleguide.xml b/xml/MAIN.styleguide.xml index 8fe6cb5..49ca341 100644 --- a/xml/MAIN.styleguide.xml +++ b/xml/MAIN.styleguide.xml @@ -2,18 +2,18 @@ - %entities; ]> -
- SUSE Documentation Style Guide<phrase condition="changes"> (with changelog)</phrase> + SUSE Documentation Style Guide @@ -80,4 +80,4 @@ -
+ diff --git a/xml/docu_styleguide.asciidoc.xml b/xml/docu_styleguide.asciidoc.xml index 9ff0e74..3419360 100644 --- a/xml/docu_styleguide.asciidoc.xml +++ b/xml/docu_styleguide.asciidoc.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Working with AsciiDoc To create documentation in the AsciiDoc format, @@ -52,4 +52,4 @@ - + diff --git a/xml/docu_styleguide.changes.xml b/xml/docu_styleguide.changes.xml index 235b5b2..7fc0613 100644 --- a/xml/docu_styleguide.changes.xml +++ b/xml/docu_styleguide.changes.xml @@ -1,5 +1,5 @@ - %entities; @@ -13,6 +13,36 @@ --> + + 2024-05 + + + + Updated the Entities subsection in + Managing documents: common types of entities and their + use cases, the Doc Kit repository that maintains official generic entities, + creating custom entities, and entity files. + + + Updated the Prompts subsection in Structure + and markup with clearer info on using prompts and prompt entities + (always specify regular or elevated privileges). + + + Terminology update: flash disk → flash drive, in sync with TermWeb. + + + Language and Terminology updated with + info about TermWeb that is now fully launched and available to all SUSE employees. + + + The style guide changed its structure to the three-column layout with clearly + featured subsections. + + + + + 2024-02 diff --git a/xml/docu_styleguide.content.xml b/xml/docu_styleguide.content.xml index fd11caf..c749631 100644 --- a/xml/docu_styleguide.content.xml +++ b/xml/docu_styleguide.content.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Documentation content @@ -35,4 +35,4 @@ - + diff --git a/xml/docu_styleguide.language.xml b/xml/docu_styleguide.language.xml index a256160..0aea851 100644 --- a/xml/docu_styleguide.language.xml +++ b/xml/docu_styleguide.language.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Language @@ -38,14 +38,14 @@ Style, 15th Edition. - +
Abbreviations Avoid using abbreviations, especially unusual ones. Avoid creating plurals of abbreviations, unless the abbreviation is an acronym or initialism. - +
Acronyms Introduce acronyms by providing the expansion in parentheses after the @@ -70,8 +70,8 @@ For clarity, avoid using possessive forms of acronyms. For example, do not use XMLʼs specification. - - +
+
Latin abbreviations Do not use Latin abbreviations. Use the full English form: for example, @@ -79,18 +79,18 @@ exception to this rule, the abbreviation etc. is allowed. - - +
+
Units of measurement You may use abbreviations of common units of measurement. For more information about units of measurement, see . - - +
+
- +
Biases and inclusiveness Do not artificially limit your audience by excluding or offending members @@ -118,11 +118,11 @@ Chicago Manual of Style, 5.43. For information about names of example items, see . - +
- +
Capitalization of headings and titles - +
Most titles: sentence-style capitalization Sentence-style capitalization is the most common capitalization used in @@ -133,8 +133,8 @@ content. An example for sentence-style capitalization is Ceph core components. - - +
+
Document titles: title-style capitalization For document titles, such as book, article, and set titles, use @@ -189,10 +189,10 @@ Guide (book title) or Kernel Module Packages for SUSE-Based Distributions (article title). - - +
+
- +
Commas Use commas to separate elements in a series of three or more elements, @@ -204,17 +204,17 @@ by a comma. For example, Before using YaST Online Update, configure a network connection. - +
- +
Contractions Do not use contractions (such as don't), unless you are purposefully writing a casual document. - +
- +
Dashes Use en dashes (–) between numbers in a range in tables and figures. @@ -223,17 +223,17 @@ For punctuation, use em dashes (—). Do not surround em dashes with spaces. Use em dashes sparingly. - +
- +
End of sentence punctuation End sentences in a period. Avoid using exclamation marks. Restrict question marks to question and answer sections. - +
- +
File and directory names Under Linux, objects like directories, printers, or flash drives are all @@ -284,9 +284,9 @@ When it is necessary to refer to file extensions, such as in compound words like PDF file, always capitalize the extension. - +
- +
Headings When writing a descriptive section, use a noun-based heading title, for @@ -303,9 +303,9 @@ For advice on how to nest sections, refer to . - +
- +
Hyphens Generally, hyphens are used as joiners for two or more words that form a @@ -362,16 +362,16 @@ when they occur after a noun. For example: This is the up-to-date version and The calendar is up to date. - +
- +
Lists For information about creating lists, see . - +
- +
Numbers and measurements Write the integers zero through nine as words. Use numerals for all other @@ -388,17 +388,17 @@ For more information, see The Chicago Manual of Style 9.6 and 9.16. - +
- +
Possessives Do not use possessives of acronyms and trademarked terms. Avoid possessives of inanimate objects. - +
- +
Prefixes Add a hyphen after the prefix to prefixed words only if you foresee @@ -409,9 +409,9 @@ For more information about using hyphens, see . - +
- +
Quotations Use quotations to quote from sources, such as books. In all other cases, @@ -463,17 +463,17 @@ Suds may froth, the sign reads. - +
- +
Semicolons Avoid using semicolons to join sentences. You may use semicolons in place of commas in very complicated series. - +
- +
Sentence structure Form clear and direct sentences with 20 words or less. Avoid complicated @@ -490,18 +490,18 @@ the action itself. As an example, write: To save the settings, click OK. - +
- +
Slashes Do not use slashes except when they are part of a standard technical term, such as TCP/IP or client/server. - +
- +
Tense Use the simple present tense. Apply the simple present tense even to @@ -509,9 +509,9 @@ prerequisites of an action. For example, If this happens, go there. or Glibc is installed. - +
- +
Tone and voice Maintain a professional tone. Do not use contractions, except in casual @@ -544,9 +544,9 @@ To refer to other parts of the document, start with For more information (about), see. - +
- +
Trademarks Most products referenced in the documentation are trademarked. Follow @@ -576,9 +576,9 @@ For more information about markup aspects, see . - +
- +
User interface items When referring to labels of user interface items, do not include ending @@ -602,5 +602,5 @@ For more information about markup for UI labels, see . - - +
+ diff --git a/xml/docu_styleguide.manage.xml b/xml/docu_styleguide.manage.xml index 87678ca..ebd3006 100644 --- a/xml/docu_styleguide.manage.xml +++ b/xml/docu_styleguide.manage.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Managing documents @@ -12,7 +12,7 @@ manage documents. - +
Remarks Use remarks for editorial comments. Remarks can be placed within, before, @@ -71,9 +71,9 @@ - +
- +
XML comments XML comments can be used for temporarily disabling portions of text. @@ -86,9 +86,9 @@ For information about formatting XML comments, see . - +
- +
Entities Entities are used to expand text. There are several situations in which @@ -119,7 +119,7 @@ automatically be expanded everywhere within the document. - +
Common types of entities Official generic entities are maintained in the Doc Kit repository. @@ -233,9 +233,9 @@ Never add this tag to the content within command and systemitem elements. Capitalizing anything inside these elements makes the content ambiguous. - +
- +
Using entity files &suse; uses a set of custom entities. Find these entities in the *.ent @@ -315,10 +315,10 @@ - - +
+
- +
XInclude elements XInclude elements are used to create modular source files that are easier @@ -351,5 +351,5 @@ parse="text" to the xi:include element. - - +
+ diff --git a/xml/docu_styleguide.name.xml b/xml/docu_styleguide.name.xml index f7ee533..f71376d 100644 --- a/xml/docu_styleguide.name.xml +++ b/xml/docu_styleguide.name.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Names of example items @@ -15,16 +15,16 @@ See also . - +
Domains Use and as example domains. Both domains were registered for use in documentation. - +
- +
Host names Use objects of the solar system: For the most important system, use @@ -32,9 +32,9 @@ planets such as earth or mars. - +
- +
IPv4 addresses Use addresses from the class C subnet 192.168.255.0 @@ -44,9 +44,9 @@ network ranges. For more information, see . - +
- +
IPv6 addresses Use addresses from the subnet 2001:0db8::/32 for @@ -58,14 +58,14 @@ For more information, see . - +
- +
Users For example users, use free-software mascots, such as Tux (Linux Kernel), Wilber (The GIMP), Geeko (&suse;), Foxkeh (Firefox), Konqi (KDE), or Duke (Java). - - +
+ diff --git a/xml/docu_styleguide.outline.xml b/xml/docu_styleguide.outline.xml index 08adc74..bd688de 100644 --- a/xml/docu_styleguide.outline.xml +++ b/xml/docu_styleguide.outline.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Outline of a manual @@ -13,7 +13,7 @@ the document structure are documented here. - +
Books For books, use a document structure that includes the following elements, in @@ -287,9 +287,9 @@ - +
- +
Articles For articles, use a document structure that includes the following elements, @@ -317,5 +317,5 @@ - - +
+ diff --git a/xml/docu_styleguide.smartdocs.xml b/xml/docu_styleguide.smartdocs.xml index 2b1b235..80b01f2 100644 --- a/xml/docu_styleguide.smartdocs.xml +++ b/xml/docu_styleguide.smartdocs.xml @@ -1,10 +1,10 @@ - %entities; ]> - @@ -59,7 +59,7 @@ repository. - +
Using ITS tags with assemblies Assembly files use ITS tags and attributes which flag whether the content of the tag should be translated or not. In the following example, the ITS attribute indicates that the @@ -333,9 +333,9 @@ ultrashort description for social media, max. 55 chars</meta> - +
- +
Revision history A revision history lists all the high-level changes @@ -423,5 +423,5 @@ ultrashort description for social media, max. 55 chars</meta> - - +
+ diff --git a/xml/docu_styleguide.structure.xml b/xml/docu_styleguide.structure.xml index 1beacd3..ae73135 100644 --- a/xml/docu_styleguide.structure.xml +++ b/xml/docu_styleguide.structure.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Structure and markup @@ -87,7 +87,7 @@ - +
Admonitory and advisory paragraphs To make readers aware of potential problems and recent changes, or to @@ -188,9 +188,9 @@ Always wait until formatting has finished. - +
- +
Application names When referring to an application, add a @@ -202,9 +202,9 @@ This will not result in a visual change but disables hyphenation in browsers. This markup sidesteps hyphenation issues of CamelCased names. - +
- +
Callouts Callouts allow annotating examples, such as configuration files or commands @@ -354,9 +354,9 @@ default 0 - +
- +
Command-line input and command-line output When dealing with user input and system output shorter than 30 @@ -474,7 +474,7 @@ default 0 - +
Commands Commands can be embedded in running text or presented as part of a @@ -503,8 +503,8 @@ default 0 See also . - - +
+
File names A file name is the name of a file on a local or network disk. Can @@ -518,8 +518,8 @@ in the directory <filename>/etc/sysconfig</filename>. follow the naming conventions at . - - +
+
Literals Use @@ -527,8 +527,8 @@ in the directory <filename>/etc/sysconfig</filename>. to mark up data taken literally from a computer system. To create a comment, insert <literal>#</literal> characters. - - +
+
Placeholders To mark up text that readers need to replace, use the @@ -540,8 +540,8 @@ in the directory <filename>/etc/sysconfig</filename>. To list the contents of a directory, execute <command>ls <replaceable>DIRECTORY</replaceable></command>. - - +
+
Prompts When documenting commands entered into Bash with a @@ -574,8 +574,8 @@ in the directory <filename>/etc/sysconfig</filename>. user, root and sudo prompts. For more information, see . - - +
+
Screens Screens are used to present: @@ -728,8 +728,8 @@ data home lost+found opt run srv tmp</screen> See also , , , and . - - +
+
Variable names To reference to names of variables, use the @@ -738,10 +738,10 @@ data home lost+found opt run srv tmp</screen> To select another display manager, start the YaST system configuration editor and change the value of <varname>DISPLAYMANAGER</varname>. - - +
+
- +
Cross-references Use the xref @@ -809,9 +809,9 @@ and change the value of <varname>DISPLAYMANAGER</varname>. Do not prefix or suffix cross-references with text labels such as appendix, chapter, table, or figure. Such labels are generated automatically. - +
- +
Emphasis Where possible, indicate stress with language only. If that is not @@ -826,9 +826,9 @@ and change the value of <varname>DISPLAYMANAGER</varname>. This will be displayed in <emphasis>italics</emphasis>. This will be displayed in <emphasis role="bold">bold</emphasis> - +
- +
Examples Use examples to illustrate complex processes. The rules established in @@ -902,9 +902,9 @@ will be displayed in <emphasis role="bold">bold</emphasis> - +
- +
External links Information that is relevant within &suse; documentation is often @@ -1023,9 +1023,9 @@ will be displayed in <emphasis role="bold">bold</emphasis> and . - +
- +
External links to &suse; documentation The &suse; documentation is hosted under documentation.suse.com. @@ -1158,9 +1158,9 @@ will be displayed in <emphasis role="bold">bold</emphasis> - +
- +
Figures For figures within lists or procedures, use the @@ -1300,15 +1300,15 @@ will be displayed in <emphasis role="bold">bold</emphasis> - +
Graphics Keep graphics as simple as possible. Use as little text as possible. To allow for translation, reserve twice as much space for runs of text as the English version of it consumes. - - +
+
Screenshots Use screenshots to illustrate complex situations in which the user @@ -1421,10 +1421,10 @@ will be displayed in <emphasis role="bold">bold</emphasis> - - +
+
- +
Glossaries An optional glossary contains terms and their definitions. Make sure that @@ -1492,9 +1492,9 @@ will be displayed in <emphasis role="bold">bold</emphasis> </glossary> - +
- +
Identifiers @@ -1807,9 +1807,9 @@ xml:id="tab-install-source" - +
- +
Lists &suse; documentation uses the following types of lists (the respective XML @@ -2000,7 +2000,7 @@ xml:id="tab-install-source" - +
Itemized lists Use itemized lists whenever the order of list items is irrelevant. @@ -2043,8 +2043,8 @@ xml:id="tab-install-source" - - +
+
Ordered lists Use ordered lists when items have a strict order, hierarchy or importance. @@ -2092,8 +2092,8 @@ xml:id="tab-install-source" - - +
+
Variable lists Use variable lists when defining terms or describing options. @@ -2161,10 +2161,10 @@ xml:id="tab-install-source" - - +
+
- +
Keys and key combinations Capitalize all keys as printed on a standard keyboard. Capitalize all letter @@ -2357,9 +2357,9 @@ xml:id="tab-install-source" - +
- +
Outline levels and sectioning Create sections using the @@ -2382,9 +2382,9 @@ xml:id="tab-install-source" For more information about writing headlines, see . - +
- +
Procedures Use procedures to describe sequential tasks. A procedure consists of the @@ -2542,9 +2542,9 @@ xml:id="tab-install-source" - +
- +
Products Always use the preferred product name instead of, for example, an @@ -2554,9 +2554,9 @@ xml:id="tab-install-source" hyphenation: <phrase role="productname">LibreOffice</phrase> is an office suite. - +
- +
Profiling Profiling is convenient for the creation of consistent documentation @@ -2642,9 +2642,9 @@ Entire hard disks are listed as devices without numbers, such as - +
- +
Questions and answers Use questions-and-answers sections to present information about @@ -2819,9 +2819,9 @@ Entire hard disks are listed as devices without numbers, such as - +
- +
References to other external resources sknorr, 2014-01-22: This section could probably use a better structure instead of this mishmash. @@ -2881,9 +2881,9 @@ Entire hard disks are listed as devices without numbers, such as Other types of references to resources are described in and . - +
- +
Tables Use tables to present many similar facts. Tables are easy to @@ -3143,9 +3143,9 @@ Entire hard disks are listed as devices without numbers, such as - +
- +
User interface items To mark up single user interface items, use @@ -3210,5 +3210,5 @@ Entire hard disks are listed as devices without numbers, such as - - +
+ diff --git a/xml/docu_styleguide.taglist.xml b/xml/docu_styleguide.taglist.xml index 3b4388b..951967b 100644 --- a/xml/docu_styleguide.taglist.xml +++ b/xml/docu_styleguide.taglist.xml @@ -1,10 +1,10 @@ - %entities; ]> - - +
Using DocBook tags - +
Meta elements All the elements at the section level and above, and many other elements, @@ -274,9 +274,9 @@ titleabbrev - +
- +
Structure elements @@ -464,9 +464,9 @@ qandaset - +
- +
Block elements The block elements occur immediately below the component and sectioning @@ -776,9 +776,9 @@ warning - +
- +
Inline elements Inline elements are used to mark up running text. In published documents, @@ -1205,10 +1205,10 @@ xref - - +
+
- +
Using ITS tags With GeekoDoc 2, it is possible to use the Internationalization Tag Set (ITS) @@ -1230,5 +1230,5 @@ xref Click <guimenu its:translate="no">Save</guimenu>. - - +
+ diff --git a/xml/docu_styleguide.techwriting.xml b/xml/docu_styleguide.techwriting.xml index 4710dd3..a28332b 100644 --- a/xml/docu_styleguide.techwriting.xml +++ b/xml/docu_styleguide.techwriting.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Writing technical documentation @@ -73,4 +73,4 @@ For more information on how to produce meaningful content that will rank high on the Web, see and . - + diff --git a/xml/docu_styleguide.webwriting.xml b/xml/docu_styleguide.webwriting.xml index d2f1660..8c8852b 100644 --- a/xml/docu_styleguide.webwriting.xml +++ b/xml/docu_styleguide.webwriting.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Writing for the Web @@ -12,7 +12,7 @@ optimized for the Web. - +
Topical structure The most important thing to do with your Web copy is to help users get @@ -52,9 +52,9 @@ - +
- +
Writing SEO-friendly content SEO, or Search Engine Optimization, is the strategy to attract organic @@ -158,9 +158,9 @@ - +
- +
Writing for a global audience Remember that every document is a potential candidate for localization (translation). @@ -243,5 +243,5 @@ - - +
+ diff --git a/xml/docu_styleguide.xmlformat.xml b/xml/docu_styleguide.xmlformat.xml index 8c50ac8..655f169 100644 --- a/xml/docu_styleguide.xmlformat.xml +++ b/xml/docu_styleguide.xmlformat.xml @@ -1,10 +1,10 @@ - %entities; ]> - + Formatting XML @@ -187,4 +187,4 @@ daps-xmlformat (for a single file). Note that while these tools are very good otherwise, they do not reflow XML comments properly. - +