Trainz/Local Style Manual

Purpose

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

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, contributors 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)

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

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

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

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

All chapters follow a template?

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?

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.

Advantages
Disadvantages

Use navigation templates

About
Advantages
Disadvantages

Use an index?

About
Advantages
Disadvantages

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.

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

Other Stylistic Concerns

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

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