local manual of style for Osmo Documentation

This is the beginning of a Local Manual of Style. For day to day help see Composition of a book page. Link to this on the same page as the table of contents in the OSMO documentation book.

According to a wikipedia article on user manuals or user guides (of March 2013), the sections of a user manual often include:

A cover page
A title page and copyright page
A preface, containing details of related documents and information on how to navigate the user guide
A contents page
A guide on how to use at least the main functions of the system
A troubleshooting section detailing possible errors or problems that may occur, along with how to fix them
A FAQ (Frequently Asked Questions)
Where to find further help, and contact details
A glossary and, for larger documents, an index

Section styles

The style suggestions below are adapted from selected wikibook recommendations, and can be made more specific for the Osmo Documentation project.

Main page and Cover Page style

scope summary
intended audience summary
layout of the book with table of contents

The main page Layout is primarily the full table of contents with other template items such as category template, completion stage template {{status}}, author info template, {{subjects}} template, printable versions, interlingual links etc.

Table of Contents style

The table of contents is on the main page.

Introduction style

The introduction page delves more deeply into topics summarized on the Main Page or Cover Page. These include purpose and goals of the book; what the book aims to teach, who the audience is, what the book's scope is, what topics the book covers, history of the subject, reasons to learn the subject, and any conventions used in the book.

Bibliography style

A bibliography is useful for collecting resources that were cited in the book, for linking to other useful resources on the subject that go beyond the scope of the book, and for including works that can aid in verifying the factual accuracy of what is written in the book. When used, such pages are commonly named Further Reading, References, or similar.

Glossary style

A glossary lists terms in a particular domain of knowledge with the definitions for those terms. A glossary is completely optional and is most useful in books aimed at people new to a field of study. Glossary should always be used for such a page.

Appendices style

An appendix includes important information that does not quite fit into the flow of a book. For example extensive software version notes or examples of code. This book may have more than one appendix. Examples of common ways to name appendices are Appendix/Keywords and Appendix:Formulas.

Software Versions and Code style

This appendix section has more extensive software information than might be appropriate for the primary sections of the documentation text. The "how-to" sections and "FAQ's" can reference this appendix.

Complete software version notes relevant to the book, page, or section at hand may use templates available at Wikibooks:Templates.

Footnotes and References style

Implementations for footnotes and references: use {{note}} to place notes at the bottom of the page and {{ref}} to reference these at appropriate places in the text. The other places the references between <ref> and </ref> tags right in the text, and then uses the {{reflist}} or <references /> to automatically generate a list of these at the bottom of the page.

See also: Help:Editing#References

Other Formatting styles for Osmo Documentation Project

Linking

Deep sub-page hierarchy navigation links help readers find their way throught the text. Use Templates to maintain consistency, including navigational aids on the necessary pages.

See also: Help:Editing#Links

See also: Wikibooks:Templates/Navigation

Navigation aids are links included on pages to make navigating between pages easier. Navigation aids can help make reading books easier for readers, but can also make maintaining and contributing to books harder. Most web browsers can back track through pages already visited, and the wiki software also adds links for navigating back to the table of contents if pages use the slash convention in their name and a book's main page is the table of contents as suggested. Using a book-specific template to hold navigation aids (rather than copy-and-paste onto each page of the book) can help reduce some of the maintenance issues, since only that template must be edited if things change. There is no standard for navigation aids. Navigation aids are optional due to their potential drawbacks.

Font styles

The first use of a word or phrase akin to the title of the page is marked in bold and when a new term is introduced, it is italicised.

Print and PDF versions style

Print versions are often named Book Name/Print version. Place markers before and after: File:Bookname.pdf for the entire book at once in a single PDF file. When someone creates a PDF version of a book, mention that PDF file at Wikibooks:PDF versions, and place {{PDF version}} on the table of contents to link to that PDF file. See Help:Print versions for more on print versions.