ParadiseStation Wiki:Manual of Style/Layout

It is important for articles to be laid out in a specific way to slowly feed information to uninformed players and also ensure that all relevant information is included. Most information in our codebase is not easily presented in a linear way and requires heavy thought in order to present it in the most helpful way. Finally, layout ensures that our wiki is accessible and navigable.

Page Types

It is important to denote

• Location Pages:

Pages

Introduction

All pages outside of Navigation and Location pages, should have an introduction paragraph (or paragraphs) capturing the essence of the article as well as summarizing all information that will be fed to the reader. The first sentence of the introduction should mention the article title/topic in bold and then provide a concise and clear definition of the subject material. The paragraphs in the introduction should breakdown all information in the article by summarizing each section of the article into 1-2 sentences each. A single paragraph will suffice generally but for especially lengthy or content heavy articles it may be useful to summarize each major section of the article into their own paragraphs. A good example of this is the Guide to Security's introduction.

The idea of a good introductory paragraph is that it is applying a definition to the topic material to help put into scope what reader should be learning from it. If a reader has an idea of what they should be looking out for and what the article is attempting to teach, they will be more easily able to understand the subject material. Additionally, if one does not have the time to read through a long article but just needs to have a superficial understanding of the subject matter, then a solid introduction to the article will give them exactly what they're looking for without requiring a ton of digging for only introductory material.

Body Sections

Body sections are hard to define as they can encompass many different types of information and presentation styles. Generally they can be broken into two categories: Explanatory material and content definitions. Generally, Explanatory Material sections will be found more often on Guide pages and Content Material sections will be found more often on item pages. As a rule of thumb, KEEP THESE SECTION SEPERATE FROM EACHOTHER. It may be necessary to provide a summary to a Content Material section in an explanatory manner so the reader knows what they're looking at, but otherwise each type of presentation style serves its own unique purpose and negatively resonate with eachother.

Explanatory Material

Explanatory material sections are body sections that serve the sole purpose of breaking down game mechanics and explaining them to the reader. The effectiveness of these sections are reliant on the rhetoric of the writer and the method in which information is presented. It is very easy to show and tell a reader what they're looking at or how to do something, but it is much more difficult to enable the reader to understand the workings of a mechanic or action. For example, if one were to provide purely a diagrammed explanation of Space Law Hierarchy but not explain how each role within that hierarchy interacts with each other and with Space Law itself then the reader will know the hierarchy but not exactly how to apply or put it into the context of the game. This is very similar to teaching school children math concepts and then teaching them how to apply that math in their actual lives, such as teaching percentages and then relating that to taxes or product markups/markdowns.

There is no magic formula for writing a good explanatory material section as its completely reliant are good writing skills. However, a writer can set themselves up for success by establishing a topic sentence at the beginning of a paragraph that introduces the information that is about to be presented to the reader. And then in the following sentences providing proper evidence/information breaking down the topic for the reader. Finally, in the last sentences of the paragraph, the writer should analyze the material and put it in context of not only the topic but the article as a whole so that the reader doesn't just read the material but learn how to apply it in context of what they're trying to learn.

Content Material

Content material sections are equally as important but serve a completely separate purpose of defining game mechanics and items. These sections are generally lengthy but concise and simple. In order to actually explain a topic to a reader, one must introduce all the items/mechanics involved in it. For example, if a writer is attempting to explain how to be a Janitor, it does not make sense to try and explain efficient or effective cleaning techniques without first defining each janitorial item and how they mechanically interact with the world around them.

There is a formula for content material, what is not explained in well-written lists should be put into tables generally. The object needs to be defined with its in-game name, sprite/image if applicable, and then a short description defining its interactions with the world and how to activate the mechanic if relevant. It's a cold statement of fact that lays out all information for the reader to use for whatever means they wish, trying to explain the content during the definition process may muddle the definition of the object and in the process fall-short of helping the reader put the mechanic in context of the game.