Remerciez-le!

Remerciez @Admin pour avoir partagé cet document gratuitement, de la manière la plus simple, en partageant sur les réseaux sociaux.

17/09/13 Documentation Style Guide doc.opensuse.org/products/opensuse/Styleguid

17/09/13 Documentation Style Guide doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/ 1/32 Documentation Style Guide SUSE and openSUSE Publication Date 25 Jun 2012 Version 2 $Revision: 39 $ Build Date: June 25, 2012 Legal Notice Copyright (c) 2007 Novell, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Section being Trademark Policy, with the Front-Cover Texts being Documentation Style Guide and SUSE and openSUSE. A copy of the license is included in Appendix B, GNU Free Documentation License. Disclaimer. All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Novell, Inc., SUSE LINUX Products GmbH, the authors, nor the translators shall be held liable for possible errors or the consequences thereof. Trademark Policy. Novell, the Novell logo, the N logo, SUSE, openSUSE, and the SUSE “gecko” logo are trademarks and registered trademarks of Novell, Inc. in the United States and other countries. Linux is a registered trademark of Linus Torvalds. All other third party trademarks are the property of their respective owners. Contents 1. Creating a Consistent Structure 2. Writing and Editing 3. Creating Procedures 4. Presenting Computer Elements 17/09/13 Documentation Style Guide doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/ 2/32 5. Entities 6. Indexing 7. Preparing Glossary Entries 8. Spelling Terms 9. Inserting Comments A. Markup Conventions A.1. Use of Identifiers A.2. The Book Structure A.3. Block Structures A.4. Inline Structures B. GNU Free Documentation License B.1. PREAMBLE B.2. APPLICABILITY AND DEFINITIONS B.3. VERBATIM COPYING B.4. COPYING IN QUANTITY B.5. MODIFICATIONS B.6. COMBINING DOCUMENTS B.7. COLLECTIONS OF DOCUMENTS B.8. AGGREGATION WITH INDEPENDENT WORKS B.9. TRANSLATION B.10. TERMINATION B.11. FUTURE REVISIONS OF THIS LICENSE B.12. ADDENDUM: How to use this License for your documents Abstract This document contains SUSE-specific style and layout issues and writing guidelines. It identifies and describes several issues to standardize the style of SUSE and openSUSE documentation. This document also contains a reference part for the XML markup used by the SUSE editors and intended for openSUSE projects, such as Lessons for Lizards. This document refers to the following documents: The Chicago Manual of Style, 15th Edition Norman Walsh's DocBook: The Definitive Guide (TDG) 17/09/13 Documentation Style Guide doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/ 3/32 Norman Walsh's DocBook: The Definitive Guide (TDG) http://www.docbook.org/tdg/en/html/docbook.html 1. Creating a Consistent Structure It is important to maintain a relatively consistent structure within a document. This structure may vary for different books or projects. For consistency, each project should have its own guidelines offered here, in a separate project document, or through templates. 1.1. Lessons for Lizards The standard base structure of LfL is reflected in its template. Find the template in LfL's SVN. The project is still in development stages. Once the project is more stable, guidelines will be added here. 1.2. Official SUSE Manuals A SUSE manual consists of the following mandatory elements: title page, copyright notice, table of contents, preface, and chapters split in sections. Optionally, use parts, appendixes, a glossary, and an index, if appropriate. Find descriptions and usage of these elements in the following list. Title Page The title page contains logo, title, and subtitle. Imprint The second page (imprint) lists edition, copyright notice, and the names of all contributors to the manual. Enter the names in the following files: authors-chapters.xml List authors. authors-trans.xml List all translators who worked on the manual. authors-office.xml List the members of the documentation department who wrote and edited the manual. This file is only used in internally-produced documentation. 17/09/13 Documentation Style Guide doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/ 4/32 the manual. This file is only used in internally-produced documentation. Table of Contents The table of contents is generated automatically. Preface The preface of a book contains a brief overview of the scope and content of the manual, information about how to read it, and typographical conventions. Parts Parts structure a manual with many chapters to improve the usability of a book. Use nouns as part titles and keep them clear and concise. Some typical part titles would be “Installation” or “Network”. Chapters Chapters typically consist of the following elements (appendixes may be regarded an exception): Figure 1. Structure of a Chapter in SUSE Documentation (* for optional element) chapter | +--- title | +--- abstract | +--- section . | . +--- introductory text . | . +--- procedure environment* . | . +--- subsection . . . . . . . +--- subsection . | . +--- troubleshooting* . | . +--- for more information* . +--- troubleshooting* | 17/09/13 Documentation Style Guide doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/ 5/32 | +--- for more information* Abstract The abstract should provide a brief summary of the information provided in the chapter. Rather than writing about what the chapter does, summarize the information the chapter contains. This gives the reader a clear idea of what he or she can learn by reading the chapter. Example 1, “An Example Abstract” is an example abstract from the chapter about file systems. Example 1. An Example Abstract openSUSE 10.2 ships with a number of different file systems, including ReiserFS, Ext2, Ext3, and XFS, from which to choose at installation time. Each file system has its own advantages and disadvantages that can make it more suited to a scenario. Professional high-performance setups may require a different choice of file system than a home user's setup. Introductions Any introductory information follows directly after the abstract and should not be placed in a separate section. Sections Structure the detailed information in sections for better user orientation and to allow the experienced user to find the desired aspect of the topic easily. Create sections in analogy to the main tasks, like installing, configuring, monitoring, and administering. If helpful, split sections into subsections. Sections start with an introductory paragraph outlining the focus of the section. If the section works with a sequential task, you can follow this introduction with a procedure description, as discussed in Section 3, “Creating Procedures”, which clearly states all the necessary steps to accomplish a task. Experienced users familiar with the topic can follow this brief sketch. For less experienced readers, each step of the procedure can contain a link to a subsection where the necessary background is provided and the action explained in more detail. In HTML and PDF online documentation, these links are clickable, providing easy access to the additional information. Troubleshooting Section If you know of common mistakes, pitfalls, or problems a user might 17/09/13 Documentation Style Guide doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/ 6/32 encounter in this situation, list them in this section. Use the title “Troubleshooting” for all these types of sections in all manuals. Structure the section in a symptom and solution pattern. For More Information As described in Section 2.2, “Addresses”, this section contains links to all sources of information that might prove helpful in the given context. Follow the general referencing guidelines in Section 2.7, “Cross-References and References to External Resources” when creating this kind of section. Glossary The optional glossary contains important terms in alphabetical order and provides a brief explanation. 2. Writing and Editing These rules are intentionally kept brief and simple. They contain specifics related to SUSE and openSUSE documentation and sometimes standard English rules. Where relevant, specific markup may be mentioned to assist in maintaining consistency in SUSE documentation. 2.1. Abbreviations and Acronyms Most abbreviations may not be used. “etc.” may be used in parentheses and some rare instances, but not in combination with phrases like “for example” or “such as.” It should be followed by a comma. Abbreviations of common units of measure may also be used. Do not create a plural of these abbreviations by adding an “s.” Use a nonbreaking ( ) space between the numeral and multiple-letter abbreviations. Do not use a space before single-letter abbreviations. A header must not contain both the acronym and the meaning. Common acronyms can be used in the header and written out in the following text. Once the acronym has been presented in the written out form, use the acronym version in the rest of a chapter. Because sometimes chapters and parts are used in different documents, it is important to map acronym and meaning at least once per chapter. Be consistent with this mapping. If you use the acronym followed by the written out form in one chapter, try to do this in all others. Form plural forms of acronyms by adding a lowercase “s,” for example, “CDs” and “BIOSs.” Because some rare acronyms create plurals by adding “'s,” avoid using 17/09/13 Documentation Style Guide doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/ 7/32 possessive forms of acronyms for reasons of clarity. 2.2. Addresses SUSE documentation contains “For More Information” sections at the end of most chapters to point to further sources of information regarding the topic. Whenever possible, links and addresses are grouped there and presented by means of a variablelist environment (link plus explanatory remarks). Do not use a list environment for only one link. If you need to present a large number of links, group them by topic and create a uploads/s1/ documentation-style-guide.pdf