This page is semi-protected.

Help:Local manuals of style

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

Unlike Wikipedia or Wiktionary—which are essentially very large books with a single manual of style—the individual books found on Wikibooks can be written in vastly different styles, according to the needs of the topic and the preference of the authors.

  1. There is a general Wikibooks:Manual of Style, which should be read before writing a local manual of style for a new book.
  2. It is highly recommended to think about the structure of the book before you begin or to create a draft as a sub-page of your user page.
  3. If the book should have unique recurring style elements, like boxes for exercises or anecdotes, these elements should be available as templates and be listed and explained in the local manual of style.
  4. If the book should have a strategy for content grouping or navigation this strategy should be explained in the local manual of style.
  5. If the book should have certain requirements for the creation of further artwork or pictures that should be mentioned in the local manual of style.
  6. A book with many authors can become inconsistent if some authors agree on a certain writing style and other authors do not follow that style. A specific writing style should be described in the local manual of style.
  7. A book that aims to follow a certain didactic approach may need special considerations from the contributing editors. The didactic approach should be explained in detail in the local manual of style.

Purpose

Wikibooks are normally a creation of many contributors, maintaining a single "voice" and style, in order to provide users with a consistent experience when using the work becomes of extreme importance. It is something that should be considered before it becomes a burden to the collaboration and a defining factor for the overall quality of the work.

While the Wikibooks:Manual of Style has a few tips that apply to all books, each individual Wikibook typically has its own local manual of style that attempts to describe the desired "voice" and explains how to use book-specific templates and other helpful tools that only apply to that one book.

Language

When possible, books should attempt to be neutral to all English speakers, and not rely on mannerisms or language specific to one region. Books require a consistent use of language and so, somewhere along their evolution a decision needs to be made whether the book will rely on British English or American English, or whether to use a simple subset of either of those languages (like small words for children, simple English, or E-Prime, etc.).

Basic structure

Flat structure (Book/chapters)

The flat structure is often preferred, because it's easier to keep organised and to link to. "Flat" means that there is only one level of subpages (Book/chapter1, Book/chapter2).

Advantages
Allows for easy linking both within the book and from other books and projects.
  • From the main page, chapters can be linked to using [[/Chapter/]].
  • Within the book, chapters can be interlinked using the form [[../Chaptername/]], rather than using the full header.
  • From other books and projects, templates are much simpler if only one variable needs to be entered, e.g. {{See also [[Book/{{1}}]]}}, etc.
Disadvantages
The automatic headers on the top of the page only lead to the main book page, rather than to section headings.

Deep structure (Book/chapters/subchapters/subsubchapters/etc.)

The deep structure has a stronger inherent organisation. "Deep" means that there are more than one level of subpages (Book/chapter1, Book/chapter1/section2, Book/chapter2/section5/page9).

Advantages
The organizational structure is "built in", so that subchapters auto-link to main chapters, allowing for easier navigation within the book
Disadvantages
Linking between chapers, other books, and other projects can become more arduous
Changing the position of a chapter in the book is more difficult than a single edit to the main book page. See Meta: Accidental linking and hard-wired category schemes.
Does not look as "neat" when printed out.

Examples

Naming conventions

Use "Name of this Chapter", "Name of Section"

Most books (both on Wikibooks and in print) capitalise all words except for articles and prepositions.

Advantages
Looks better when printed, since it follows the standards of most published books.
Disadvantages
May be harder to link to.

Use "Name of chapter", "Name of section"

Some books (both on Wikibooks and in print) capitalise only the first letter of book and chapter titles

Advantages
More familiar "wiki" style of naming, as established on Wikipedia
Disadvantages
Doesn't conform to normal book publishing styles.

Examples

Page length restrictions

Restricted page length

Some books may have a limit on page length (Wikipedians for example try to limit page length for articles). The absolute limit per page is 2,097,152 bytes (2,048 kB), as defined by MediaWiki software.

Advantages
Limiting page length will make chapters easier to download for users with slow connection speeds.
May be helpful to set an arbitrary limit on page length to give the book a more consistent feel.
Disadvantages
May bring about arbitrary section breaks that might otherwise not be warranted.

Templates

It's often helpful to use templates for each chapter or page, in order to create a consistent structure. A template can create an outline using headers, infoboxes, and other features to make each chapter of a book resemble others.

Advantages
Gives the book a consistent feel.
It is much faster to make a change in a template than to edit every single page by hand.
Disadvantages
Can be limiting.
Makes it more difficult for new contributors.

All chapters follow a template?

Some books may benefit from the use of standardized templates for the chapters.

Advantages
Makes it easier to ensure that every chapter follows the same format.
Disadvantages
Depending on the template, it may be harder to create variety across pages.
Makes it more difficult for new contributors.

Different templates for different types of chapters?

Some books may use different templates for different types of pages. The Cookbook, for example, uses different templates for recipes, ingredients, etc.

Advantages
Allows a more customized (yet consistent) style for pages that discuss general types of topics.
Disadvantages
Can make the book difficult for new contributors to get used to.

Complex templates?

Some very useful and attractive templates can be made using parser functions.

Advantages
Attractive and flexible.
Disadvantages
Difficult for inexperienced authors to use.

Examples

Wikilinking

Use only intra-book piped links?

Restricting links to only the chapters of a book makes the book "self contained"

Advantages
Keeps the book together, without needing to rely on external sources.
Disadvantages
Requires making a new page for every term

Use cross-project links?

Links can be made across Wikimedia projects using prefixes within the brackets. w: leads to Wikipedia, wikt: leads to Wiktionary, etc.

Advantages
Allows easy explanations of terms
Disadvantages
Makes the book rely on other projects. If this kind of linking is done, authors should check periodically to make sure the destination page has not been moved.

Restricted links?

Books might use wikilinks for certain cases only, when the information being linked to is well beyond the scope of the book.

Many books restrict links outside the book to a "Further reading" section on each page. Some go even further and restrict links outside the book to a single "Bibliography and resources" page.

Advantages
Makes the book comparatively self-contained, so it remains useful if the book is printed or the user has no internet connection.
Disadvantages
Links at the end of a page or section are not as easy for the reader to find as links that are included in the text of the book itself.

Navigation

Use navigation templates?

A navigation template can be used to create an index, table of contents, or other book features.

Advantages
It is easier to use a template to create a professional-quality navigation feature than trying to reinvent the wheel.
Disadvantages
Makes it more difficult for new contributors.

Use an index?

An index is a detailed list, usually arranged alphabetically, of the specific information in a book.

Advantages
Easier for the reader to find the information he or she is looking for.
Disadvantages
The index has to be compiled based on information from the book, and maintained as things are added or removed.

Images

Images used in Wikibooks are stored in the File: namespace, either on Wikibooks or on Wikimedia Commons, a separate but closely-related wiki.

Fair use

"Fair use" images are copyright-protected works that are allowed to be used in certain circumstances under U.S. law. These images are stored on Wikibooks and a legal justification has to be made for every use.

Advantages
Allows more images to be used than if fair use images are not acceptable for a book.
Disadvantages
This is a gray area of the law and particularly affects people who access Wikibooks from outside the United States, because use of such material might contravene local laws.

Commons only?

Wikimedia Commons hosts media that is either in the public domain or licensed by the copyright holder for free re-use by anyone.

Advantages
By only using images that are on Commons, it is easier to transwiki the book (e.g. if German Wikibooks wants to make a translation, they can copy it over without having to make a legal justification for each image).
The images are often organised in Commons galleries and categories, which can help with locating related and/or better images for the book.
Disadvantages
Fair use images are not permitted on Commons.

Use thumbnails?

Thumbnails are small versions of an image, that can be expanded by clicking.

Advantages
Allows many images to be placed on a page without taking up too much space or bandwidth.
Disadvantages
Thumbnails are often too small to be useful in printed versions.

Categories

Use a single category for all book chapters?

Advantages
Keeps the whole book "in one place", so it's easy to keep track of pages.
Disadvantages
Categories display up to 200 pages of a single type at a time with links between each group, because of a restriction in the MediaWiki software. This could be a limitation for larger books with more than 200 pages because the links are to preceding and/or following groups. This can be mitigated by using a template like {{CategoryTOC}} to enable easier navigation within the category.

Use subcategories within the book?

Advantages
Helps to group together related sections of a particular book
Disadvantages
Makes it more difficult to see all chapters at once.

Mathematical formulae

Many books, in the mathematics, science, and engineering bookshelves, contain mathematical formulae and use special notations to display mathematical concepts. When such formulae or notations are used, they should be consistent throughout the entire book. For example, some books have a LMOS that recommends using 2+3i vector notation, while other books have a LMOS that recommends using 2+3j vector notation.

Print versions

See also: Help:Print versions and Using Wikibooks/Print versions and PDFs

Books can have one or more printable versions and can include PDF versions for easy reading and downloading. Print versions should use page transclusion so that all updates to the main book pages are automatically reflected in the print version text. PDF versions should be updated on a regular basis, to maintain consistency with the main book pages.

There are a number of specialized templates and magic words for use with print versions and PDF versions. For example, print versions can use __NOTOC__ to suppress the automatically-generated table of contents (TOC) in the book. In this way, the printed version can produce its own TOC.