Trainz/Local Style Manual

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

Purpose[edit]

The goal of "Trainz" is to serve as a learning tool and a reference. Our audience includes brand new users looking to fill in the gaps in the manual. On the other end of the spectrum we have experienced users who want to expand their skills. Such a wide audience can be challenging.

We have adopted a structure similar to a textbook. We take the reader from where they typically start to increasingly more advanced topics. Authors should keep in mind that each part should progress in a similar manner. Also, authors should not assume prior knowledge other than what is in this book.

Wiki-books are written by many authors. Each book should have a consistent "voice" and style. That provides the reader with a consistent experience using the book. The rest of this document provides guidelines to assist authors and editors in creating a coherent and valuable resource for all Trainz users.

Language[edit]

Books require a consistent use of language. Either British or American English may be used, at least for now. Regardless, contributors must remember that English is not the primary language for many Trainz users. Use plain language principles, particularly for word choices and sentence structure. When possible, contibutors should attempt to be neutral to all english speakers, and not rely on mannerisms or language specific to one region.

Trainz brings together computer software and railroading. Each field has its own terminology. Authors should not assume that readers already have a command of either. Define specialized terms on first use and in the glossary.

Basic structure: Deep structure (Book/Chapters/Sections/Subsection/Topic)[edit]

The deep structure has a stronger inherent organisation. "Deep" means that there are more than one level of subpages. "Trainz" uses a deep structure though contributors should resist defining pages beyond four levels (Chapter, Section, Subsection, Topic).

Naming conventions[edit]

Use "Name of this Chapter", "Name of Section"[edit]

Most books (both on wikibooks and in print) capitalise all words except for articles and prepositions. Do not use the words "chapter," "section," "susbsection," or "topic" in the title.

Page length restrictions[edit]

Restricted page length[edit]

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

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 resemple others.

All chapters follow a template?[edit]

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

Advantages
Gives the book a consistent feel.
Disadvantages
Can be limiting.
Makes it more difficult for new contributors.

Different templates for different types of chapters?[edit]

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

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

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

Examples[edit]

Wikilinking[edit]

Use only intra-book piped links?[edit]

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

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

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

Advantages
Disadvantages

Navigation[edit]

Use navigation templates[edit]

About
Advantages
Disadvantages

Use an index?[edit]

About
Advantages
Disadvantages

Images[edit]

Fair use[edit]

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

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

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

Use a single category for all book chapters?[edit]

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 organisation of the book

Use subcategories within the book?[edit]

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

Cross-categorise to major topics?[edit]

Advantages
Makes the book more "visible", for readers who use the category system to navigate or look for source material for other books.
Disadvantages
Can clutter the bottom of the page with long lists of categories.

Mathematical Formulae[edit]

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 throughtout the entire book.

Other Stylistic Concerns[edit]

  • Use __NOTOC__ on all pages? (this tends to look better on printed versions)

Print versions[edit]

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. [[category:Trainz Admin|*Style guide}}