Help:Local manuals of style

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

About Wikibooks
FAQs
Glossary

Navigating

Pages
Tracking changes
Account management

Contributing

Editing
Categories
Files
Tables
Templates
Variables
Formulas
Quizzes
Styling
Collections
Importing

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 what best suits the topic and the preference of the authors.

  1. The first thing to note is that there is a Wikibooks:Manual of Style. Before you write a manual of style for a new book you probably should have read the Wikibooks:Manual of Style.
  2. It may be useful to imagine 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 manual of style.
  4. If the book should have a strategy for content grouping or navigation this strategy should be explained in the 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 manual of style.
  6. A book with many authors can become inconsistent if some authors agree on a certain writing style and some authors do not follow that style. A specific writing style should be described in the 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, if any, should be explained in detail in the manual of style.

Purpose

Wikibooks are normally a creation of many contributors, maintaining 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).

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

Fair use

"Fair use" images are those that are copyrighted, but are considered to be fair game for public use.

Advantages
Allows for more images to be used than if fair use images are not acceptable for a book.
Disadvantages
Definitely a gray area of law, and it might be better to simply avoid using these .

Commons only?

Images used in wikibooks can either be stored in the wikibooks image namespace, or on commons.

Advantages
By only using images that are on commons, it makes it easier for other projects to transwiki the book (e.g., if German Wikibooks wants to make a translation, they can copy it over without having to chase down the images).
The images will likely be organised into galleries and/or categories on commons, which might lead the author to 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 for 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.
Disadvantages
For larger books with more than 200 pages, the category page will be broken up.
Limits the structure of the book

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 make use of mathematical formulae. Also, these books will also frequently rely on various notations to denote different mathematical concepts. Whenever a book makes use of such formulae or notations, 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

Many books have a printable version, and some books even have multiple printable versions. Many books also include PDF versions for easy reading and downloading. Print versions should use page transclusions so that all updates to the main book pages are automatically reflected in the print version text. PDF versions should likely be updated on a regular basis, to stay consistent with the text.

There are a number of specialized templates for use with print versions and PDF versions. For more information, see Help:Print versions.

Print versions may typically want to use the __NOTOC__ magic word to suppress the automatically generated TOC in the book. In this way, the printed version can produce its own TOC.