User:Runfellow/MOS prototype

The Wikibooks Manual of Style serves to establish good structural and stylistic practices to help editors produce higher quality wikibooks.

Wikibook titles

See also Wikibooks:Naming policy for information on how to name books and their chapters.

Wikibooks should be titled based on their aspect. This is a combination of the target audience, scope, and depth of the book. Several books on one topic but with differing aspects can exist. For example, a book on woodwork aimed at the general public may be entitled simply Woodworking, or a mathematics text for commerce students may be called Mathematics for Commerce or Commercial Mathematics instead of simply Mathematics.

Some people prefer to use title casing like books often do, while others prefer to use sentence casing like Wikipedia does. Title casing is recommended for book titles, as it reduces the potential conflict between title- and subject-categories. Casing for subpages and sections is entirely a matter of style. Whatever combination of schemes for book titles, pages, and sections, please be consistent and follow the existing style for books you are editing.

Subpage names that describe what the chapter is about. For example, "Notating The Game" is preferred over numbered chapters like "Chapter 10". This way, inserting new chapters or reordering chapters requires less work.

Structure

See also book design for some helpful tips and ideas.

Main page

The main page is generally the first page a reader sees. It should give a quick overview of the scope, intended audience, and layout of the book. Splash pages should be avoided. Often, the layout is simply the full table of contents. The main page should contain certain elements (required elements are in bold):

• A table of contents In cases where this is impractical, a special page can be created for it. Common names for such pages are "Contents", "Table of contents", or similar.

• Table of Contents Examples
• 
  Standard TOC
• 
  2 column TOC
• 
  2 column TOC

• Collections
• print versions
• PDF versions
• {{subjects}} templates for subject pages. If you need help with categorizing a book, please request assistance in the reading room.
• A completion {{status}} to provide readers with an idea of how far along the book is when browsing.
• Interlingual links. Books across language projects may be dissimilar even when about the same subject, however, so be wary about placing interlingual links on any other pages.

Links to the book from the card catalog office and external websites should point to a book's main page. The subject index on the card catalog office requires the {{subjects}} template to be placed on the main page of the book. The book's main page and category should be placed in any categories that the book belongs to.

Introduction

An introduction page is the first page where learning begins. A book's introduction page commonly delves into 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, any conventions used in the book, or any other information that might make sense in an introductory chapter. Common names for such pages are "Introduction" or "About". The latter is more commonly used when information about the book is split from the introduction of the subject matter.

The local manual of style – when it is not part of the "Introduction" – is often named "Local style manual", "Manual of style", "How to contribute", "How you can help", "About", etc. Whatever it is called, link to it on the the table of contents. Having a local manual of style is further discussed in WB:LMOS.

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.

Bibliography

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

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

An appendix includes important information that does not quite fit into the flow of a book. For example a list of math formulas might be used as an appendix in a math book. Appendices are optional and books may have more than one appendix. Examples of common ways to name appendices are Appendix/Keywords and Appendix:Formulas.

Examples:

• Conlang/Appendix/Glossary
• Inkscape/Appendix:Reference

Cover pages

Cover pages are useful for print versions. These should be separated from the main page (remember: Wikibooks is not paper) but can be used to make print versions. When used, commonly named Cover.

Print versions

See Help:Print versions for more on print versions. They are often named Book Name/Print version.

PDF versions

Some books have a File:Bookname.pdf for the entire book at once in a single PDF file. If someone creates a PDF version of a book, it would be nice if that PDF file were mentioned at Wikibooks:PDF versions, and {{PDF version}} were placed on the table of contents to link to that PDF file.

Examples

• Control Systems has a great introduction describing (and linking to some of) the prerequisites for this book.
• Spanish uses a splash page, but the table of contents is well annotated and accessible.
• Haskell has a very nice layout sectioned off for audiences of different levels.

Style

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

Headers

Headers should be used to divide page sections and provide content layout. Primary information should be marked with a "==", and information secondary to that should be marked with a "===" header, and so on, for example:

== Animals ==
There are many kinds of animals.

=== Cats ===
Cats are animals.

=== Dogs ===
Dogs are animals.

There is no need to provide systematic navigation between headers; only provide navigation between pages. A list of sections is automatically provided on the page when more than 3 headers are used.

Linking

Books with a deep sub-page hierarchy should include navigation links to help navigate within the hierarchy. Templates can help maintain consistency by making it easy to include navigational aids on the necessary pages.

Footnotes and references

Wikibooks has a couple of really simple implementations for footnotes and references. One uses {{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.

Mathematics

Format using HTML or in-line Mediawiki markup when using variables or other simple mathematical notation within a sentence. Use <math></math> tags for more complicated forms.

Use italics for variables: a+b, etc. Do not use italics for Greek letter variables, function names, or their parenthesis.

To introduce mathematics notation in a display format, move to the start of the new line, add a single colon, and then the notation within the <math></math> tags. If punctuation follows the notation, do so inside the tags.

For example:

Markup	Display
: <math>\int_0^\infty {1 \over {x^2 + 1}}\,dx = \frac{\pi}{2},</math>	$\int _{0}^{\infty }{1 \over {x^{2}+1}}\,dx={\frac {\pi }{2}},$

is correctly used for "display" guidelines.

If a notation does not render as a PNG, you may force it to do so by adding a "\,\!" at the end of the formula.

Software

Books that are about computer software or rely on the use of computer software to illustrate examples should clearly indicate which version of the software is relevant to the book, page, or section at hand. Templates to help with this and examples of their usage is available at Wikibooks:Templates.