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.

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.

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 possessive forms of acronyms for reasons of clarity.

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 separate list environment for each group. Provide a comprehensive title for each of the groups or an introductory sentence.

Translators are normally provided with localized versions of links in the comments of the source code. If none is provided, the English default is used as fallback.

You can provide links or addresses directly in the main sections, but are encouraged to use and refer to the “For More Information” section wherever possible. Both automated checks and the use of editor comments for translators ensure that the links are kept up-to-date.

For detailed information about external and internal references and addresses in SUSE documents, refer to Section 2.7, “Cross-References and References to External Resources”.

SUSE uses four different kinds of admonitory and advisory paragraphs. Because these elements are formatted in a way to draw the reader's attention to them, their use should be limited to specific situations. Additionally, avoid using more than one per page.

It is generally not necessary to describe the intended audience in the text, but keep it in mind when writing the document. Adjust the tone, style, and technical level of the text based on the intended audience. Do not insult them by saying something is obvious.

Aim the document at the reader by describing tasks the reader may need to complete rather than the organization of the program. For example, when describing YaST, focus on how to configure the devices and services the user needs rather than the module structure and available dialogs.

Try to focus on the positives: what the program can do rather than its limitations. Be honest in your documentation and avoid absolutes and the exaggerations of marketing-speak.

Use title-style capitalization for all types of headings and titles, including figure and table titles. This style is explained in Chicago 8.167.

This style can be very complicated to implement, but the following these simple rules is a good start:

In variable lists, capitalize the term in title-style unless it is a complete sentence. In all list items, use sentence-style capitalization (capitalize the first letter and proper nouns only). Use title-style for row and column labels in tables.

SUSE and openSUSE documentation does not normally permit the use of contractions. Contractions are only permitted in casual documents and texts. A good example of appropriate use of contractions is the SuSE tour that was included in older releases. It provided a friendly and somewhat humorous introduction to applications and was aimed predominantly at the the home user.

Use xref when you refer to an appendix, chapter, part, preface, section, table, figure, or example. The referenced element needs an id attribute. When referencing these elements, do not insert a text label like “appendix”, “chapter”, “part”, “preface”, “section”, “table”, “figure”, and “example”. These are inserted automatically.

Do not insert a reference to a paragraph (para). If you need a reference to a list, insert id and xreflabel.

References to man pages and info pages should generally be made in the format “the man page of command” or “the info page of command”. In a situation where the category of the page is needed, add “(man 9 command)” to the end.

Use ulink for a URL, like http://www.suse.de. Always use the correct protocol prefix (http, ftp, mailto) to enable the automated link check. Never use filename for this kind of link. Anything that should show up as a clickable link in the final HTML and PDF docs must bear the correct markup. Otherwise risk breaking the link checking tools and rob the user of extra functionality, such as click to reach extra external documents. Do not enter a text label for the ulink so that the URL itself appears in printed versions.

Do not use ulink and the file: prefix to reference filenames. Use filename for files.

Do not use links across documents where ID and IDREF linking is not possible and ulink is inappropriate. For references to information in SUSE books outside the current document set, use the appropriate macro for the book title. The reference should not refer to a specific chapter or section number or title because these things change too easily. Instead, make a reference using the document title but no specific headers.

Insert references to external (not SUSE or openSUSE) books in the format "Title by Author (ISBN #)." Inclusion of the ISBN is optional. Place the title in citetitle tags. For example:

<citetitle>Indexing Books</citetitle> by Nancy C. Mulvany
(ISBN 0-226-55014-1) is a useful guide for indexing.

It is useful to provide language-specific references in the translated books. If the authors know of language-specific versions, they can include them in comments to the translators. As time permits, translators should look for corresponding language-specific resources. For URLs, provide only the language-specific version of a site. Use the English as a fallback. For books, provide the title of the translated version along with the original title if such a translation exists.

Refer to Chicago 5.43, 5.51, and 5.78 for suggestions of how to avoid gender bias. Basically, rewrite the sentence to avoid indications of gender. If possible, use plural to allow use of “they” as the pronoun. If these attempts fail, use “he or she.”

For example users, use the various mascots, like Tux, Geeko, and Wilber.

Each level of heading should have two or more headings. Lonely subheadings are not allowed. Make headings in a group parallel by using a similar structure for the wording.

Keep headings short and simple. Do not use both an acronym and the written-out form in a heading.

Provide content between a heading and its subheadings. In some cases, this is only a small paragraph of introductory information. In other cases, more information can be provided.

SUSE and openSUSE documentation uses the following types of lists (the respective XML tags are given in parentheses):

Consider the following general rules when creating or editing list environments:

The different types can be nested, but avoid nesting too many levels. When nesting different types of lists or introducing multiple levels of one type, always consider the flow of the text. It is rarely necessary to have more than one level in a list. Using too many levels disrupts the text flow, confuses readers, and heavily influences the document layout. Consider these issues carefully before nesting lists or introducing another list level. Restructuring the information using a well-balanced combination of lists and flowing texts may prove a good approach.

Follow Chicago 9.6 for numbers. This is basically to write out single-digit numbers (0–9) and use numerals for all others. For measurements, always use numerals when an abbreviation is used for the unit.

Do not use possessives of acronyms and trademarked terms. Unless use of a possessive with an inanimate object improves the clarity of a sentence, avoid inanimate possessives.

Use commas between all items in a series. For example, write “a, b, and c.” Use commas around phrases like “for example” and “that is.” Introductory phrases in the beginning of a sentence are normally followed by a comma. For example, “Before using YaST Online Update, configure a network connection.”

Semicolons (;) are mainly used to join two independent but related sentences. They can also be used in place of commas in a complicated series. It is preferable to avoid them when possible and instead break the text into smaller pieces.

em dashes (—) are punctuation dashes. Use them sparingly and do not surround them with spaces. en dashes (–) should be used between numbers in a range in tables and figures. Also use them for a hyphenated term when a two-word term is part of the hyphenated term (file system–specific). Additionally, use them as the symbols for minus signs.

Do not use slashes except when they are part of a standard technical term, such as TCP/IP or client/server. Avoid the use of exclamation marks (!).

Keep sentences clear and direct. Avoid complicated clauses and try to keep sentences short (under 20 words). Avoid joining sentences with semicolons (;) if they can be as easily understood as two independent sentences. Make sure that the relationship between subject, verb, and object are clear. Avoid ending a sentence with a preposition where reasonable.

Use tables to present a large number of similar facts. A table makes them easy to scan and compare when presenting the same information textually would require several paragraphs.

Always keep tables as simple as possible. They should not require extensive explanations in the related text and should make sense even to those readers who are not very familiar with the topic.

A table always has a title. If you assign an id, it can be identified and referenced by this attribute.

Value and description pairs are better handled by means of a descriptive list.

Maintain a professional tone. Except in casual documents, do not use contractions. Do not use humor. It does not translate well and may be misunderstood by nonnative speakers.

Use second person (you) to refer to the reader. Normally the reader is the user or administrator that does the actions described. Do not overuse “you.” It is often understood, especially in directions.

Use active voice. Active voice means that the subject of the sentence performs the verb. For example, “The root user performs administrative tasks” is active voice. “Administrative tasks are performed by the root user” is passive voice. Passive voice can be used occasionally if there is a need to place emphasis on the object of the verb or if the doer of the action is unknown. “A SAMBA server must be configured in the network” is an example of proper use of passive voice. The emphasis is on the server, not on the person configuring it.

Use the simple present tense in almost all cases. This also applies for sentences with “if” or “when” clauses. “If you do this, something happens.” “When you do that, something else happens.”

When referring to an application, do not use any markup at all:

Linux commands are case-sensitive, so always present them as they appear in the system. Commands can be embedded in the flowing text or presented as part of screen environments or examples. In flowing text, use command when referring to an actual command you would use on a command line:

Place options inside the command tags. Options can also be used in text, separately from command. See Section A.4.3, “Commands and Options”.

Do not use any markup for commands as part of a screen environment. Anything inside this environment appears verbatim.

There are currently two different kinds of variable environments used in SUSE documentation:

SUSE documentation is limited to describing the Linux operating system and open source applications. The following sections summarize the common naming and markup principles that apply to SUSE and openSUSE documentation.

SUSE uses a small set of custom entities. This set is localized for each supported language. Find the SUSE set of entities in the file entity-decl.ent under each documentation project and each language. When the set has been modified for a new product release, this file must be updated in the supported languages as well.

Each header of a SUSE XML file includes the entity declaration file (by means of an entity):

<!ENTITY % entities SYSTEM "../entity-decl.ent">
%entities;

<!ENTITY exampleserver   "sun">
<!ENTITY exampleserverip    "&exampledomainip;.20">
<!ENTITY exampleserverfq    "&exampleserver;.&exampledomain;">

A few hints for working with entities in SUSE documentation projects:

The following provides some background on the most important entities used in creating documentation for SUSE products. To be able to adjust product names of platform branding even past any deadlines, a set of entities must represent the frequently-changing product names. The same applies to book titles. An entity-decl.ent file contains several different categories of entities. These are:

There are several guidelines to consider when working with product entities for SUSE documentation:

Remarks are used for the majority of editorial comments. It is possible to have them be visible in the built document, improving the editing process. Remarks must be placed before or after a para but inside section tags.

Include a role to show the importance and type of remark. Available roles and their uses are:

The writer of the remark should start the remark with his or her username followed by a colon (:). Others responding to the remark should insert their username, a colon, and comments inside the tags but starting on a new line. Comments should be deleted by the original writer when they consider the issue resolved. The following is an example remark:

<remark role="needinfo">tux: couldn't find the option for foo
geeko: see /usr/share/doc/foo.html</remark>

XML comments are primarily used for temporarily disabling portions of text. Because they can appear at any point in a file, they can also be used to point the reader of a remark to the appropriate point in a text.

The final use of comments is to mark changes made for layout reasons. The following is an example of a layout comment.

<!--layout tux: split para -->

	Valid Comments
Do not use -- in comments. The use of -- causes errors.