Wikibooks:Manual of Style

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", and 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, as books often do, while other people prefer to use sentence casing, as Wikipedia does. Title casing is recommended for book titles as it reduces potential confusion between title- and shelf-categories. Casing on subpage names 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.

Sub-page names that describe what the chapter is about — for example, "Chess/Notating_The_Game" — are preferred over numbered chapters — like "Chess/Chapter_10" — so that inserting new chapters in between existing 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 new 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. Collections, printable versions and PDF files should be easily accessible from this page.

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 {{shelves}} 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. Indicate a book's completion status with {{status}} to provide readers with an idea of how far along the book is when browsing the shelf pages. If you still require help with categorizing a book, please request assistance in the reading room.

Interlingual links should be placed on the book's main page. Books across language projects may be dissimilar even when about the same subject. Be wary about placing interlingual links on any other pages.

Table of contents

In general, the table of contents should be on the main page, giving readers an overview of the available material. 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

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 page -- is often named literally "Local style manual", "Manual of style", "How to contribute", "How you can help", "About", etc. — appended to the book name, of course. Whatever it is called in the book you are editing, it would be nice if a link to it is on the same page as 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 parentheses.

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.

Colors

Be careful in the use of colour to maintain accessibility.

Nesting

Nesting refers to when subchapters are nested/below/each/other/like/this. In some cases, this may be appropriate, such as with large textbooks that contain subsections with a lot of content. Avoid creating excessive subchapters that each contain very little content—instead, consider merging these into a single chapter, with headers to divide the content as appropriate. Additionally, when nesting, it is important to have an intuitive and accessible navigation system. Having tables of contents "hidden" within subchapters is usually inappropriate, as this makes it difficult to view the book structure at a glance and navigate between sections. It also presents challenges for automatically-updating navigation templates such as Template:Nav. Instead, it is usually better to link all subchapters in the main table of contents as follows:

• Chapter 1
  • Subchapter A
    • Subchapter α
• Chapter 2
• etc.