VNDev Wiki:Manual of Style
This Manual of Style (abbreviated MoS) is the guide for writing all content for the VNDev Wiki. A number of guidelines in this Manual have been adapted from the Wikipedia Manual of Style.
Please also be sure to follow our Contribution Policy.
Articles vs Guides
Articles are informational and encyclopedic in nature. Their purpose is to, as objectively as possible, document the visual novel development space and its components, including prominent individuals, companies, and titles, as well as the components and techniques of development itself. Articles are not meant to teach the reader how to develop, nor to prescribe best practices. It may be appropriate to note if a particular technique is popular or industry-standard, but such information should serve a documentation, not advice, purpose.
Guides are instructional and prescriptive in nature. They are primarily written by one user or a small group of users, and serve as a tool for passing on advice and techniques to less experienced developers. Guides typically contain advice, suggestions, and/or step-by-step tutorials.
Scope
If a subject is simple and discrete enough that a single guide could provide a beginner to intermediate understanding of how to complete the task and/or implement the technique in development, a guide should be created in place of an article.
If a subject is complex enough that at least two guides are required to impart a beginner to intermediate understanding of the topic, or if there are multiple variations of a subject (ex. layered sprites in Ren'Py vs NaniNovel vs other engines), then an article (or section of an article) is warranted (assuming it also meets the other article topic guidelines, below). One or more guides may also be created.
Requirements for Guides
- Main article: VNDev Wiki:Manual of Style/Community Guidance
Article topics
The subject of an article must be:
- Specific: Well-defined, does not significantly overlap with other articles.
- Notable: Has been discussed at some length, including by people who did not originate/create the topic. For example, Doki Doki Literature Club warrants an article because it has been significantly discussed by the community, but not every released visual novel does.
- Substantive: There is a significant amount of information about the topic that is useful to visual novel developers. The article, in its finished state, will be longer than a few sentences, not be a simple dictionary definition.
- Directly related to visual novel development or VN development communities.
Page titles
All page titles (both for guides and articles) must be:
- Written in sentence case. Capitalize only the first word, except for proper nouns or other words for which capital letters are always used.
- Recognizable – The title is a name or description of the subject that someone familiar with, although not necessarily an expert in, the subject area will recognize.
- Natural – The title is one that readers are likely to look or search for and that editors would naturally use to link to the article from other articles. Such a title usually conveys what the subject is actually called in English.
- Precise – The title unambiguously identifies the article's subject and distinguishes it from other subjects.
- Concise – The title is no longer than necessary to identify the article's subject and distinguish it from other subjects.
- Consistent – The title is consistent with the pattern of similar articles' titles.
- Lacking acronyms, except when the acronym is the most common name for the subject.
- In singular form (Sprite instead of "Sprites")
Titles of Guides must also meet additional requirements.
Redirects
Redirects are pages which help users find the page they're looking for by forwarding one search term to a different page. Redirects should be created for:
- Alternative names for the same subject (Tom Rothamel redirects to PyTom)
- Common alternative capitalizations or other correct spellings (Renpy and RenPy redirect to Ren'Py
- Abbreviations and initialisms (VNDB redirects to The Visual Novel Database)
- Closely related terms (Sprint redirects to Sprinting)
- Component parts, where the component parts do not warrant their own article (Fade redirects to a section of Transition)
Do not create redirects for:
Language
Almost all content for the VNDev Wiki should be written in standard American English. All articles and all page titles (both for guides and articles) are included in this rule. Guides may be written in the preferred dialect or language of the author, but should use one language & dialect throughout. Guides in a language other than English must have titles which end with the language in parentheses, such as "Guide:Designing sprite expressions (Spanish)".
Layout
Articles should begin with a short introductory section, which has no header, is not broken up into sub-sections, and briefly explains the overall topic of the article. The remainder of the article's content should be broken up into sections.
Section & subsection titles should:
- Consist of plain text only (no formatting, footnotes, links, etc.)
- Instead of links within section titles, use the
{{main|NAME}}
template. Place it immediately after the section or subsection title, and replaceNAME
with the name of the article you'd like to link to.
- Instead of links within section titles, use the
- Not redundantly refer back to the subject of the article, e.g., "History", not "History of NaNoRenO" or "Its History".
- Not be phrased as a question, e.g., "Features", not "What features does Ren'Py have?".
- Be unique within the page (so that links to particular sections will work properly).
- Be written in sentence case
In general, try to avoid the following section structures:
- A section with only one subsection. Either remove the subheader, or split it into a separate section.
- One or two sections on the page, with only one of them having many subsections. Consider adjusting the subsections to be full sections.
Writing style
Articles are intended to be encyclopedic, and as such, should use an objective and informative writing style. In general, plain English should be used, avoiding slang and excessive industry jargon. Guides are often more narrative, and can use more creative and casual phrasing if the author chooses.
To make best use of the wiki format, and to allow readers to easily navigate between articles, include relevant and appropriate links to articles and guides within your body text.
In body text, page titles, and section titles, avoid abbreviations such as "VN" and "devs", except when abbreviations are the most common way of referring to a subject (such as VNDB) or when abbreviations are part of a set name or phrase (such as VNConf).
Use of Standard Templates
To facilitate ease of use and navigation, and to maintain a uniform appearance, use of templates such as Infobox
es, Navbox
es, and Ambox
es is encouraged, and in some cases required.
Infoboxes
Variations of the standard Infobox
template provide uniform, easily-skimmable information about a group of objects of the same type where each has its own article.
Existing types of Infoboxes:
- Template:Infobox person
- Template:Infobox organization
- Template:Infobox website
- Template:Infobox bot
- Template:Infobox jam
Infoboxes should contain basic facts about the subject of the article, designed to facilitate basic factfinding and a quick understanding of the subject. Facts should be brief, and long quotations or detailed descriptions are not permitted. In the best-written articles, Infoboxes should not contain any information that is not also located in the body of the article. There are intended as quick reference only - not a replacement for a fully-written article.
Infoboxes must be placed after an article's introductory paragraph(s), but before its first section heading.
If including an image in an Infobox, set its size (width) to 200px.
Navboxes allow easy navigation between related groups of articles.
When used, they must be placed at the very bottom of the page. If a navbox is included in a page, the page must be listed in that navbox.
Amboxes
Amboxes are small boxes which appear at the top of a page or section and contain a small amount of information about the article itself (rather than the article's subject).
Maintenance Flags
The most common use of Amboxes on VNDevWiki is as "flags" to indicate that an article or section is in need of maintenance or improvement.
Existing maintenance flags include:
- Template:Outdated - the article contains outdated information, or does not contain the most up-to-date information
- Template:Cleanup - the article is poorly organized and/or has grammar and spelling mistakes
- Template:Split to guide - the article contains non-encyclopedic information, and it has been proposed that such information be split into a guide
- Template:Image requested - the article would benefit from one or more additional images
- Template:Needs examples - the article would benefit from examples
- Template:Empty section - the section is empty
- Template:Expand article - the article needs expansion
- Template:Expand section - the section needs expansion
- Template:Merge - it has been proposed that the article be merged with one or more other articles
Pages that contain maintenance flags are automatically added to the appropriate .
Spoiler Warnings
Template:Spoiler warning must be used to warn readers if an article, guide, or section contains plot spoilers for a visual novel or other story.
Guide Disclaimers
Every Guide is required to begin with {{Template:Guide}}
. See the documentation for that template for more details.