Summary
A good, concise structure will benefit the quality of all Wiki articles. This document will serve as strong recommendation for writing such articles. In general:
- Be to the point, and stay on topic.
- Write on the level of a novice, not an expert.
- Link to other sources on the Wiki if needed/possible. Make the link specific, target a specific header. If a link is missing, annotate so by adding (link missing) directly after the phrase that should link to another article.
- Order your article logically and intuitively (see also this Wikipedia article on writing better articles).
- Use the writing conventions.
- If applicable, attach a
.tmd(example) file to support your article. - Respect each other’s work. If you doubt something should be updated, feel free to leave a comment to discuss it.
Kinds of Wiki articles
Devices (link missing)
These articles will focus on a single device, e.g. the Advanced Perlin (link missing) device, discuss all parameters and ports, and common use cases for the device.
The summary should begin with describing what kind of device it is, e.g. a Generator (link missing) device, a brief description of its use case, and contain the devices icon. The article should then describe the parameters from top to bottom, as if one were to open the device in World Machine itself. Advanced parameters should be listed as well, and be annotated by adding (advanced) after the parameter’s name. When a parameter can be spatially controlled, this should be annotated by adding (spatial) after the parameter’s name. After that, ports are to be discussed, first inputs, then outputs. The article will conclude with common use cases for the device. Feel free to add screenshots of common node setups (e.g., the Flow Restructure (link missing) device followed by the Create Water (link missing) device).
If applicable, briefly address previous versions of the device, e..g. for the Thermal Weathering (link missing) device. If the device differs a lot, consider enveloping the article using a [details] section.
Device types (link missing)
These articles describe a type of device, e.g. the Generator (link missing) devices. The summary will describe what these devices do/how they are used, focusing on common/shared features (e.g., “Generator devices are the prime method to create a base terrain of your world, either by using noise or predefined shapes/patterns.”). These articles contain a list of all devices belonging to this type.
Data types (link missing)
These articles will describe a single data type, and how the data type is used in World Machine. Articles on composite types, e.g. the Water Data Type (link missing), should briefly explain the use case(s) for this composite type, explain what each component does, but not explain the data type of each component. To use the Water Data Type as an example, the article should explain what the Depth component encodes, that it is a Heightmap Data Type, and then link to it. It should not explain what a Heightmap Data Type is at that moment. This, of course, is a guideline, and if you feel clarity is gained by giving a more elaborate explanation, feel free to do so.
Workflows (link missing)
These articles should clearly state they are a guideline, and not the absolute truth. Start with a summary, which describes what this workflow aims to achieve, in what situation it should be used, and maybe also when not. When writing such an article, keep in mind you are writing it for a novice, unless you explicitly state in the article’s title the workflow is intermediate/expert level. That said, even then, make the article as accessible as possible.
Use examples that are concise, consistent and unambiguous. Use screenshots, but make them count. A workflow is not better if it has 10 screenshots when 4 would’ve been fine as well.
Is your workflow similar, or an alternative to an existing workflow? Make it clear by linking to that workflow as well, and explain in your summary what differs this workflow from the other. If the difference is small, consider adding an “Alternative approach” section at the bottom of the original article, or don’t create a new article.
GUI and Program articles
These articles will explain what certain Graphical User Interface (GUI) elements do, and how to use them. Think of articles like describing the Project Settings (link missing) dialogue.
Updating articles
It is important the articles we write, are kept up to date. Feel free to update an article you stumble upon, to the reflect the newest version of World Machine. When big/breaking changes are introduced, consider collapsing the old article
Suggestions
This guideline itself is something we, as a community, should discuss and polish over time. Feel free to post suggestions below, or edit this text as needed.
