VNDev Wiki:Manual of Style: Difference between revisions
I think this is a complete first draft. |
|||
| Line 1: | Line 1: | ||
This '''Manual of Style''' (abbreviated '''MoS''') is the guide for writing all content for the [[VNDev Wiki]]. | 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 [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style Wikipedia Manual of Style]. | ||
==Articles vs Guides== | ==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. | 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. | 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. | ||
==Page topics== | ==Page topics== | ||
===Article topics=== | ===Article topics=== | ||
| Line 20: | Line 17: | ||
* Distinct enough from other guides to be useful. Multiple guides on the same topic may exist, but each should provide a different strategy, method, or way of thinking, such that the guides are not duplicative of each other. | * Distinct enough from other guides to be useful. Multiple guides on the same topic may exist, but each should provide a different strategy, method, or way of thinking, such that the guides are not duplicative of each other. | ||
==Page titles== | ==Page titles== | ||
All titles (both guides and articles) must be: | 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. | * 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. | * 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. | ||
| Line 30: | Line 27: | ||
* In singular form ([[Sprite]] instead of "Sprites") | * In singular form ([[Sprite]] instead of "Sprites") | ||
===Guide titles=== | ===Guide titles=== | ||
The titles of all guides must be prefixed with "Guide:" with no space following (as in Guide:Finding a team on DevTalk). Guides in a language other than English must have titles which end with the language in parentheses, such as "Guide:Designing sprite expressions (Spanish)". | The titles of all guides must be prefixed with "Guide:" with no space following (as in "Guide:Finding a team on DevTalk"). Guides in a language other than English must have titles which end with the language in parentheses, such as "Guide:Designing sprite expressions (Spanish)". | ||
===Redirects=== | ===Redirects=== | ||
Redirects are pages which help users find the page they're looking for by forwarding one search term to a different page | 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: | Redirects should be created for: | ||
* Alternative names for the same subject | * Alternative names for the same subject ([[Tom Rothamel]] redirects to [[PyTom]]) | ||
* Abbreviations and initialisms | * Common alternative capitalizations or other correct spellings ([[Renpy]] and [[RenPy]] redirect to [[Ren'Py]] | ||
* Abbreviations and initialisms ([[VNDB]] redirects to [[The Visual Novel Database]]) | |||
* Plural forms ([[Sprites]] redirects to [[Sprite]]) | * Plural forms ([[Sprites]] redirects to [[Sprite]]) | ||
* Closely related terms | * Closely related terms ([[Sprint]] redirects to [[Sprinting]]) | ||
* Component parts, where the component parts do not warrant their own article ([[Fade]] redirects to [[Transition]]) | * Component parts, where the component parts do not warrant their own article ([[Fade]] redirects to [[Transition]]) | ||
==Guide ownership== | ==Guide ownership== | ||
Guides are typically written and "owned" by a single user or a small group of users. Although anyone can edit any guide, the owner of the guide generally has the final say in the content (aside from moderators). It is generally good etiquette to check with the owner of a guide before making any significant changes other than grammar and spelling. | |||
==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== | |||
===Article 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 titles should: | |||
* Consist of plain text only (no formatting, footnotes, links, etc.) | |||
* Not redundantly refer back to the subject of the article, e.g., "Early life", not "Smith's early life" or "His early life". | |||
* Not be phrased as a question, e.g., "Languages", not "What languages are spoken in Mexico?". | |||
* Be unique within the page (so that links to particular sections will work properly). | |||
* Be written in sentence case | |||
===Guide layout=== | |||
Within the first paragraph or two, guides should state their purpose, as well as what features make this guide distinct from any others on similar topics. After that point, guides may by broken up into sections (or not) as the guide author deems appropriate. If sections are used, their titles should follow the guidelines for article section titles above. | |||
==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. | |||
Revision as of 09:49, 4 July 2022
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.
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.
Page topics
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
Guide topics
The topic of a guide must be:
- A skill, process, or technique useful to visual novel developers
- Distinct enough from other guides to be useful. Multiple guides on the same topic may exist, but each should provide a different strategy, method, or way of thinking, such that the guides are not duplicative of each other.
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")
Guide titles
The titles of all guides must be prefixed with "Guide:" with no space following (as in "Guide:Finding a team on DevTalk"). Guides in a language other than English must have titles which end with the language in parentheses, such as "Guide:Designing sprite expressions (Spanish)".
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)
- Plural forms (Sprites redirects to Sprite)
- Closely related terms (Sprint redirects to Sprinting)
- Component parts, where the component parts do not warrant their own article (Fade redirects to Transition)
Guide ownership
Guides are typically written and "owned" by a single user or a small group of users. Although anyone can edit any guide, the owner of the guide generally has the final say in the content (aside from moderators). It is generally good etiquette to check with the owner of a guide before making any significant changes other than grammar and spelling.
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
Article 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 titles should:
- Consist of plain text only (no formatting, footnotes, links, etc.)
- Not redundantly refer back to the subject of the article, e.g., "Early life", not "Smith's early life" or "His early life".
- Not be phrased as a question, e.g., "Languages", not "What languages are spoken in Mexico?".
- Be unique within the page (so that links to particular sections will work properly).
- Be written in sentence case
Guide layout
Within the first paragraph or two, guides should state their purpose, as well as what features make this guide distinct from any others on similar topics. After that point, guides may by broken up into sections (or not) as the guide author deems appropriate. If sections are used, their titles should follow the guidelines for article section titles above.
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.
