User:Whiteknight/New Book Guide/Design Patterns

Whiteknight's Book Guide

Design Patterns

Developing books do not emerge fully-formed and in a perfect book shape. The process for creating a book can cause a book to take many forms which are not in themselves acceptable here at Wikibooks. However, so long as progress is continuous, various stages of books can not only be accepted here in the short-term, but also can be beneficial tools to book authors.

Books are large projects, and it is generally not conceivable that an author will be able to write, to completion, one page at a time in a linear fashion. In fact, it should be assumed that most authors are only transient members here at Wikibooks, and that they could abandon their work here at any time.

With this in mind, an author who wants to see their books succeed in the long-term should develop their book while attempting to maximize the ability for future authors to take over if the original author should leave suddenly. Books should start as a clear plan, such as a pagelist or an outline. From the outline, a page should progress to one of several intermediate forms. These intermediate forms allow a book to increase in size and information content rapidly, without needing to worry extensively about organization or formatting. After a book has expanded significantly in one of these intermediate forms, editors, revisers, and reviewers can polish the book to make it better and eventually make it a featured book. The general design pattern for a book that allows other authors to quickly and easily pick up where the original author left off is:

Outline → Intermediate Form → Book → Featured Book

Warning About Intermediate Forms

Notice that intermediate forms are not considered stable books. If a book in an intermediate form is long abandoned, it runs a high risk of being deleted. Stubs are relatively well tolerated on Wikibooks, and a large portion of our community will resist deleting them unless they are in particularly bad shape. Macropedias are against policy, and unless a transwiki will significantly improve content at Wikipedia (which is unlikely), macropedias can be quickly deleted. This is a case that is counter-intuitive: Where a book in notably better condition (a macropedia) can be deleted easier than a book in worse condition (a stub). Course-like books are better-tolerated than macropedias are, but they still run the risk of being transwikied to Wikiversity if you don't pay close attention to them.

Outlines

Outlines are not necessarily stubs because they do not need to contain any content. Outlines are a great way to plan and prepare a book, but a free-standing outline that has been long-abandoned by it's original authors are generally not helpful or valuable. In fact, they can be counter-productive because they set up a framework that other editors will be compelled to follow, but they don't provide any foothold where a new contributor can start working quickly. An empty outline is a set of limitations and no benefits, and this situation can be discouraging enough to a new contributor to drive them to start a separate book, or even leave Wikibooks entirely.

Rule: Use outlines for your personal planning work. DO NOT leave a book as a bare outline for long

The outline phase of a book should be brief. Outlines should quickly be filled with at least a base amount of content so that future authors and editors have some raw material to work with. There are tfour major directions that an outline can progress in:

Stubs: A small amount of text can be added to all or most of the pages in an outline to convert it to a stub. Stubs should contain basic information about the subject and the organization, so that future authors know what to write and where to write it. Following a form is much easier when there are guidelines. Books in this condition will likely be marked with {{Stub}} or {{Book stub}} templates.
Macropedias: Pages can be seeded with articles imported from Wikipedia. In these early stages they become a "macropedia", which is like a collection of encyclopedia articles on a single topic. Macropedias created by importing text from Wikipedia will need to be extensively de-formatted (dewikified) before future authors can begin to contribute book-like content in a meaningful way. Macropedias that are made in other ways, such as students creating encyclopedia-like chapters as part of a class project, don't need to be dewikified but they will need to be integrated together to form a smooth narrative.
Courses: During the progression of a school course, information can be "dumped" into the page as it is received. This means that things like lecture notes, reading notes, assignments and their solutions, and other information received through a course can be uploaded as they are learned. Course-like materials do not need to be de-formatted like Wikipedia articles need to be, but they often need to be restructured, organized, and edited extensively.
Content Dump: A content dump is where we start with an outline and quickly add large volumes of unstructured information to it. Content dumps lack the structure of the other types of growth patterns, but can grow at some of the quickest rates. Notice that content dumps will need major rearranging, revising to produce a consistent narrative, and formatting to make the book more attractive and approachable.

Link List

A step up from an outline is a link list. Link lists are collections of links to other books, other wikis (such as Commons, Wikipedia, or Wikisource), or other places where information about the subject can be obtained. Link lists can be helpful in organizing resources and finding places to import raw material from, but they are also very dangerous. Link lists or "Link farms" are a violation of policy, and they likely will be deleted if they do not evolve quickly. If you would like to maintain a list of resources for your own use, it is typically better to do it in your own userspace where many such content policies do not apply.

Stubs

Stubs are a page, or several pages, with only a brief amount of starter text. This starter text can often explain what the page is going to cover, and provide a small amount of introductory text that other authors can help to expand. A "good stub" should:

Explain clearly what the page will cover
Provide a brief introduction to the topic
Provide an organizational framework (named headings, for instance) to help show where information should go.

Stubs that do not contain this information are likely to be more of a hindrance than a help to future authors, and should likely be deleted.

Macropedias

A great way for some books to get started is to import related articles from Wikipedia. Wikipedia articles, after being deformatted, contain large amounts of information that can eventually be revised and rearranged to form a book module. This task isn't an easy one, but often times starting with a full page of information can help the author to see what information needs to be incorporated in the page.

Macropedias are not allowed as a final product, but they are an acceptable first stage in constructing a new book.

Courses

New books started by groups, such as class projects, often take the form of the group that created them. This means that class groups will tend to create books that follow the outline for a school course.

As in a macropedia, above, sometimes a book can get off to a great start by first dumping information on the page in a formless manner, and then shaping that book later. In that vein, a course-like book can be viewed as an early production phase for a proper book. Often, books in a course-like stage can be easily forked to Wikiversity, so that both an online course and the accompanying textbook can be in development simultaneously.

Metadata

Groups, especially class groups, tend to require a certain amount of hierarchical organization among their members. This organization often plays out in the book in the form of group meta-data such as "attendance" sheets, notes about which group members are working on which chapters, information about the project itself so that other contributors understand what's going on, et cetera. This metadata should likely be confined to the talk pages, although sometimes this isn't an attractive short-term option.

Whenever metadata is being stored in the book namespace, the long term goal should be for that data to be distilled to it's important components and moved to a special location on a page entitled "About This Book", or "Authors", or something similar. You should always be mindful that long after your group has finished working on the book, other authors will be working on it and will want to add their own names to the list of authors. They may even want to get in touch with you later to let you know how things are going.

Book

A book is not just a collection of information like a macropedia or a course-like book will be. Books should be unified and continuous with a central narrative that builds on old information in order to present new information. Starting with an intermediate form, authors should:

Rearrange materials into a logical order. Easy, fundamental concepts should go in the beginning, and more advanced concepts should be moved towards the end. Vocabulary words should be defined before they are used in the text.
Format material like a book. Long lists of bullet points or long numbered lists should be replaced with paragraphs of prose. Beyond just simple prose, a book should be written in such a way that readers will be able to learn from it, and not just be a simple presentation of facts or figures.
Remove excess markup. Excessive markup, such as large numbers of wikilinks, bold and italics text, and large lists should be removed. Markup should be used to enhance certain points, but not be used so often as to distract the reader.

Featured Book

The last development stage for a book, but certainly not the end of development, is for the book to become featured.