Osmo Documentation/Local Manual of Style

From Wikibooks, open books for an open world
Jump to: navigation, search

local manual of style for Osmo Documentation[edit]

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[edit]

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[edit]

  • 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[edit]

The table of contents is on the main page.

Introduction style[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

Linking[edit]

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[edit]

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[edit]

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[edit]

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.

Printed Cover Pages style[edit]

A cover pages for the print version should be separated from the main page, named Cover.



Future Sections Sandbox[edit]

We can change or fill out draft forms of the suggested sections below, and move them to the book as soon as they add meaningful content.

User guide
This book will help you with the ....


Introduction[edit]

The book will show you how to ...

About Osmo[edit]

Osmo is a ...

Why Osmo?[edit]

1. Always ....
2. Best ... .
3. etc

Chapters[edit]

  1. System installation
  2. FAQ - Frequently Asked Questions about Solving problems
  3. From authors

Picture gallary[edit]

osmo screenshot 1

osmo screenshot 2

osmo screenshot 3

Links[edit]

  1. Other web page: http://example.com