Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
wiki:wiki-editing-practices [2021/09/25 04:21] – Added syntax section, moved templates to batocera code snippets (renaming to something more meaningful soon), updated sidebar info atari | wiki:wiki-editing-practices [2023/03/02 23:47] (current) – old revision restored (2023/03/01 02:33) atari | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Good Wiki Editing Practices ====== | ====== Good Wiki Editing Practices ====== | ||
+ | |||
+ | <WRAP center round tip> | ||
+ | In order to create a wiki editing account, ask for one on [[https:// | ||
+ | |||
+ | New users will require their edits get approved by an approver first before it gets shown to the general public. | ||
+ | </ | ||
Recommended reading: https:// | Recommended reading: https:// | ||
+ | |||
+ | This page is about employing good practices when editing the wiki. Not the " | ||
The Batocera Wiki is a collaborative project aimed at both introducing new users to Batocera' | The Batocera Wiki is a collaborative project aimed at both introducing new users to Batocera' | ||
Line 10: | Line 18: | ||
* Can the page be put into a relevant sub-category? | * Can the page be put into a relevant sub-category? | ||
* Is the information somewhere else already, and if so, is it in the correct place? | * Is the information somewhere else already, and if so, is it in the correct place? | ||
+ | * Ultimately, // | ||
- | Once that's all done, you can now begin editing the wiki. | + | Once that's all checked for, you can begin editing the wiki. |
===== Syntax ===== | ===== Syntax ===== | ||
DokuWiki uses its own markup syntax that's similar to but not quite markdown. You can find out the specifics on the [[wiki: | DokuWiki uses its own markup syntax that's similar to but not quite markdown. You can find out the specifics on the [[wiki: | ||
+ | |||
+ | ===== Practicing ===== | ||
+ | |||
+ | When starting out, you should use [[playground: | ||
+ | |||
+ | If uploading images to a page in the playground, be sure to set the namespace of the image to your intended finalised namespace. Otherwise, when the page gets moved from the playground to its official namespace, all the images will not be visible to guest users! | ||
+ | ===== Spelling and formatting ===== | ||
+ | |||
+ | It's important to make sure you're using correct spelling and grammar, but for large documentations such as this wiki it's also useful to be consistent in the spelling of Batocera-specific terminology and to be consistent in the formatting of things such as buttons and menu items. It's generally more a rule-of-thumb than a strict guideline, but should you want your edits to look higher quality you should follow these conventions: | ||
+ | |||
+ | * **General spelling** | ||
+ | * This wiki uses American English, so as to be approachable by the widest audience possible and to assist with the auto-translator. Spelling for words such as " | ||
+ | * Level 1 title headers should be Title Cased. Remaining headers should use standard capitalization. No period marks should appear at the end of any header. | ||
+ | * Unordered bullet lists and tables should have each element end without a period mark, unless the list entries are full sentences (such as this bullet list). | ||
+ | * " | ||
+ | * When referring to specific Batocera versions, use " | ||
+ | * " | ||
+ | * " | ||
+ | * " | ||
+ | * " | ||
+ | * **Paths and file extensions** | ||
+ | * Paths to files/ | ||
+ | * Paths to directories should end with a / and paths to a file should end with their extension (if they have one). | ||
+ | * Certain file types should be referred to by their capitalized name. For example, the ISO file. It is also acceptable to use path notation with wildcard characters to indicate what can be replaced, such as '' | ||
+ | * If using a path at the end of a sentence punctuation should still be used. For example, ''/ | ||
+ | * **Button labels** | ||
+ | * Face buttons should use their graphical representation to avoid confusion, such as {{: | ||
+ | * Other buttons should use path formatting (%%enclosed in '' | ||
+ | * Shoulder buttons use their PlayStation format, such as '' | ||
+ | * Due to ambiguity with '' | ||
+ | * If needing to note buttons where formatting is not available (such as in a code block), refer to the buttons by their cardinal direction followed by their equivalent SNES button in parenthesis. Eg. Press the South button (B SNES), then the START button. | ||
+ | * **Strings and menu items** | ||
+ | * Strings that need to be replaced by the user should be enclosed in less-than and greater-than symbols, followed by a single-sentence explanation of what's being replaced. Eg. Name the file '' | ||
+ | * Menu items should be **CAPITALIZED AS THEY APPEAR IN ES AND BOLDED**, and menu navigation directions should have menu items separated by the arrow icon (->, coded as %%->%%) enclosed in spaces. Eg. Go to **MAIN MENU** -> **SYSTEM SETTINGS** -> **AUDIO**. Title Case is also acceptable. Just be consistent with it. | ||
+ | * Items selected from within menus should be enclosed in double-quotes ("). Eg. From **Audio**, select " | ||
+ | * **Images** | ||
+ | * Should you embed an image that you are not the owner of, put credits to the original work/ | ||
+ | |||
+ | ===== Tense, tone and formality ===== | ||
+ | |||
+ | This is more a subjective thing as everyone interprets tone and formality different. With that said, here are some loose guidelines: | ||
+ | |||
+ | * Use past tense for most things. Use current tense when giving instructions. For example: "has happened", | ||
+ | * Be objective and concise. Readers don't want to spend an inordinate amount of time shifting through unnecessary information. | ||
+ | * Where possible, try to avoid abbreviations. Common, universal abbreviations are okay (for example, eg., etc., OS or URL). Abbreviations are acceptable if the full name has already been mentioned in the article. | ||
+ | * Not everyone will get/ | ||
+ | * Avoid referring to the reader. If the word " | ||
+ | * Avoid unnecessary manners such as " | ||
===== New/ | ===== New/ | ||
Line 46: | Line 103: | ||
If you've created a new page, the next job is to add a link to it to [[: | If you've created a new page, the next job is to add a link to it to [[: | ||
- | * When considering which category to put it under, avoid adding anything to **Getting Started**. Put it in the category you believe would be the one a new user would use to find the information on your page. If adding a new system page in particular, it will be automatically linked in the [[: | + | * When considering which category to put it under, avoid adding anything to **Getting Started**. Put it in the category you believe would be the one a new user would use to find the information on your page. If adding a new system page in particular, it will be automatically linked in the [[: |
* Pages linked to in the sidebar should use [[: | * Pages linked to in the sidebar should use [[: | ||
* New pages should also be added to the appropriate section in the [[: | * New pages should also be added to the appropriate section in the [[: | ||
- | |||
- | ===== Practicing ===== | ||
- | |||
- | When starting out, you should use [[playground: | ||
- | |||
- | ===== Spelling and formatting ===== | ||
- | |||
- | It's important to make sure you're using correct spelling and grammar, but for large documentations such as this wiki it's also useful to be consistent in the spelling of Batocera-specific terminology and to be consistent in the formatting of things such as buttons and menu items. It's generally more a rule-of-thumb than a strict guideline, but should you want your edits to look higher quality you should follow these conventions: | ||
- | |||
- | * This wiki uses American English, so as to be approachable by the widest audience possible and to assist with the auto-translator. Spelling for words such as " | ||
- | * Level 1 title headers should be Camel Cased. Remaining headers should use standard capitalization. No period marks should appear at the end of a header. | ||
- | * Bullet lists and tables should have each element end without a period mark, unless the list entries are full sentences (such as this bullet list). | ||
- | * " | ||
- | * " | ||
- | * Face buttons should use their graphical representation to avoid confusion, such as {{: | ||
- | * Other buttons should use path formatting (%%enclosed in '' | ||
- | * Shoulder buttons use their PlayStation format, such as '' | ||
- | * Due to ambiguity with '' | ||
- | * If needing to note buttons where formatting is not available (such as in a code block), refer to the buttons by their cardinal direction followed by their equivalent SNES button in parenthesis. Eg. Press the South button (B SNES), then the START button. | ||
- | * Menu items should be **CAPITALIZED AS THEY APPEAR IN ES AND BOLDED**, and menu navigation directions should have menu items separated by the arrow icon (->, coded as %%->%%). Eg. Go to **MAIN MENU** -> **SYSTEM SETTINGS** -> **AUDIO**. Camel Case is also acceptable. Just be consistent with it. | ||
- | * Items selected from within menus should be enclosed in double-quotes ("). Eg. From **Audio**, select " | ||
- | * Should you embed an image that you are not the owner of, put credits to the original work/ | ||
- | |||
- | ===== Tense, tone and formality ===== | ||
- | |||
- | This is more a subjective thing as everyone interprets tone and formality different. With that said, here are some loose guidelines: | ||
- | |||
- | * Use past tense for most things. Use current tense when giving instructions. For example: "has happened", | ||
- | * Be objective and concise. Readers don't want to spend an inordinate amount of time shifting through unnecessary information. | ||
- | * Where possible, try to avoid abbreviations. Common, universal abbreviations are okay (for example, eg., etc., OS or URL). Abbreviations are acceptable if the full name has already been mentioned in the article. | ||
- | * Not everyone will get/ | ||
- | * Avoid referring to the reader. If the word " | ||
- | * Avoid unnecessary manners such as " | ||
===== Individual elements ===== | ===== Individual elements ===== | ||
Line 94: | Line 118: | ||
* There should be a blank line before and after your header. | * There should be a blank line before and after your header. | ||
* No two headers should share the same name as it makes it more difficult to link to, unless they are small enough sections such that linking to the header one-tier higher would make the meaning obvious anyway ([[: | * No two headers should share the same name as it makes it more difficult to link to, unless they are small enough sections such that linking to the header one-tier higher would make the meaning obvious anyway ([[: | ||
+ | * When deciding whether to use a header or a sub-header for a particular section of content, consider whether the content in the main header is **required knowledge** to understand the content being added. If it is, a sub-header is appropriate. If it is not, use a new main header. | ||
Here is an example of a page's valid header code: | Here is an example of a page's valid header code: | ||
Line 136: | Line 161: | ||
Large images should be aligned to the left or center. Small and infrequent images can use any alignment. Multiple small images should be aligned to the right and have enough text content between them so that they don't vertically overlap and push each other toward the center. If there isn't enough text content, use center alignment instead to force the text content to render below the image. | Large images should be aligned to the left or center. Small and infrequent images can use any alignment. Multiple small images should be aligned to the right and have enough text content between them so that they don't vertically overlap and push each other toward the center. If there isn't enough text content, use center alignment instead to force the text content to render below the image. | ||
+ | |||
+ | ==== Lists ==== | ||
+ | |||
+ | Unordered lists (also referred to as bullet lists) should be used to list elements that can be interpreted in any order. Ordered lists (a.k.a. numbered lists) should be used to relay instructions that should be performed in a certain order. | ||
==== Displaying code ==== | ==== Displaying code ==== | ||
Line 142: | Line 171: | ||
* Code blocks should be used for multi-line code, and in-line should be used for single strings of code. | * Code blocks should be used for multi-line code, and in-line should be used for single strings of code. | ||
- | * The %%< | + | * The '' |
+ | Secondary lines and the closing brackets in the code don't have to also follow this rule, but the next bullet point should be the next immediate line. | ||
+ | </ | ||
+ | * The only exception to '' | ||
==== Path and commands ==== | ==== Path and commands ==== | ||
Line 159: | Line 191: | ||
This wiki will automatically adjust the spacing and scaling of tables based on their content and the amount of screen-space available, so no need to worry about that yourself. | This wiki will automatically adjust the spacing and scaling of tables based on their content and the amount of screen-space available, so no need to worry about that yourself. | ||
+ | |||
+ | ==== Collapsible sections ==== | ||
+ | |||
+ | Should be avoided in most if not all cases. Collapsible sections require the user to interact with the page, which may not be compatible with certain devices, be difficult to employ, or seem amateurish. With that said, collapsible sections can be used to organize inordinate amounts of necessary information that can be irrelevant to the user currently scanning through the page, such as all the topics available in the sidebar or a really large configuration file. | ||
===== If you're not quite sure ===== | ===== If you're not quite sure ===== | ||
Compare it to how other similar pages have done it! The beauty of the wiki is that you will be covering information that hasn't been covered before, so there may not be a consistent formatting for it yet. Look at how other, similar-enough pages have formatted their information and take it from there. | Compare it to how other similar pages have done it! The beauty of the wiki is that you will be covering information that hasn't been covered before, so there may not be a consistent formatting for it yet. Look at how other, similar-enough pages have formatted their information and take it from there. | ||
+ | |||
+ | For making a new system page specifically, | ||
- wiki/wiki-editing-practices.1632536466.txt.gz
- Last modified: 3 years ago
- by atari