Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
wiki:wiki-editing-practices [2021/09/19 12:05] – added info about the sidebar atariwiki: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://discord.gg/ndyUKA5|the Discord server]].
 +
 +New users will require their edits get approved by an approver first before it gets shown to the general public.
 +</WRAP>
  
 Recommended reading: https://www.dokuwiki.org/tips:good_style Recommended reading: https://www.dokuwiki.org/tips:good_style
 +
 +This page is about employing good practices when editing the wiki. Not the "how" to do something in the wiki, but the "why". None of these are strict rules, but instead guidelines to help create higher quality articles.
  
 The Batocera Wiki is a collaborative project aimed at both introducing new users to Batocera's flow and giving extensive documentation to developers to help compiling the project. With that being said, here are some questions you should ask yourself before making an edit: The Batocera Wiki is a collaborative project aimed at both introducing new users to Batocera's flow and giving extensive documentation to developers to help compiling the project. With that being said, here are some questions you should ask yourself before making an edit:
Line 10: Line 18:
   * Can the page be put into a relevant sub-category? For example, something purely related to a single system should be appended to its relevant [[:systems|system page]].   * Can the page be put into a relevant sub-category? For example, something purely related to a single system should be appended to its relevant [[:systems|system page]].
   * 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, //something// is better than **nothing**. Even if the information is not robust or high quality enough for the wiki, it's better than a complete absence of it. It can always be revisited to be amended later. The playground can be used if help is needed with certain edits, without going straight to publication.
  
-Once that's all done, you can now begin editing the wiki. +Once that's all checked for, you can begin editing the wiki.
- +
-===== New/renaming pages ===== +
- +
-Renaming pages is highly discouraged. It should only be done in extreme cases where the original name fails to convey the content of the article. This is because search engines and links from external websites will break if the page name is changed. If absolutely sure that the rename is necessary, the page can be renamed with the "Rename page" button on the right-side toolbar (this will allow the wiki to update all the internal links to the new page automatically). A new page with the old page's name containing a link to the renamed page should be made to redirect search engines/old links. +
- +
-==== The sidebar ====+
  
-After you've created or renamed a new page, check the [[:sidebar|sidebar]] to see if any links have broken. You can also take this opportunity to add your new page to it. 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, be sure to add it to the **Systems overview** sub-category.+===== Syntax =====
  
-Pages linked to in the sidebar should use internal links with the page's proper name as the display text. The page'proper name should use regular capitalization rules, not Camel Case like the page title is on the page itself.+DokuWiki uses its own markup syntax that's similar to but not quite markdown. You can find out the specifics on the [[wiki:syntax|DokuWiki syntax page]]. The Batocera Wiki-specific syntax can be found at the [[:batocera_wiki_code_snippets|Batocera Wiki code snippets page]], though really that'more just commonly used code that's interchangeable between pages like button symbols, page templates, etc.
  
 ===== Practicing ===== ===== Practicing =====
Line 27: Line 30:
 When starting out, you should use [[playground:playground|the playground]] to test things. This page is ordinarily not visible to public search engines so any changes made here are inconsequential. You can also preview your changes before committing them with the Save button, it is good practice to do this with every edit to ensure that links and embedded images are working correctly. When starting out, you should use [[playground:playground|the playground]] to test things. This page is ordinarily not visible to public search engines so any changes made here are inconsequential. You can also preview your changes before committing them with the Save button, it is good practice to do this with every edit to ensure that links and embedded images are working correctly.
  
 +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 ===== ===== 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: 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 "color" and "bastardization" should use their American spelling. This is consistent within Batocera itself as well. +  * **General spelling** 
-  * Level 1 title headers should be Camel Cased. Remaining headers should use standard capitalization. No period marks should appear at the end of header. +    * 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 "color" and "bastardization" should use their American spelling. This is consistent within Batocera itself as well. 
-  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). +    * 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. 
-  * "Batocera" is a proper noun, so it should always be capitalized. For instance, this is how Batocera appears in the middle of a sentence. +    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). 
-  * "EmulationStation" is stylized by having capitals for both the "E" and "S". An accepted abbreviation of this is "ES", but try to use its full name especially when it's only mentioned once in the document. +    * "Batocera" and "Buildroot" are proper nouns, so they should always be capitalized. For instance, this is how Batocera and Buildroot appear in the middle of a sentence. Batocera.linux is the full name of the project, and is usually used when referring to the [[https://github.com/batocera-linux|Github page]]. It follows standard capitalization rules. For instance, this is how batocera.linux appears in the middle of a sentence. 
-  * Face buttons should use their graphical representation to avoid confusion, such as {{:wiki:south.png?nolink&20|South button (B SNES)}}. Refer to [[:batocera_wiki_code_snippets#graphical_elements|the Batocera-specific wiki syntax page]] on how to use it. +    * When referring to specific Batocera versions, use "Batocera **v<version number>** and lower" or "Batocera **v<version number>** and higher", where the "**v<version number>**" is **bolded**. Batocera versions before **v29** should be referred to by the old versioning scheme (eg. Batocera **5.27**), whereas new versions should use the single-number versioning scheme (eg. Batocera **v29**). There is no Batocera **v28**. 
-  * Other buttons should use path formatting (%%enclosed in ''%%) so they aren't translated by the auto-translator, be capitalized as they appear on their printed label and be enclosed in square brackets within the path formatting to differentiate it from actual paths. For example, ''[START]'', which is coded as %%''[START]''%%. +    * "EmulationStation" is stylized by having capitals for both the "E" and "S". An accepted abbreviation of this is "ES", but try to use its full name especially when it's only mentioned once in the document
-  * Shoulder buttons use their PlayStation format, such as ''[R1]'' and ''[L2]''. Refer to the first-tier shoulder buttons as buttons, and the second-tier triggers as triggers. +    * "Wi-Fi", "Bluetooth" are stylized proper nouns, and should always be capitalized in their stylized format. For instance, that's how the [[hardware:compatible_dongle_list|compatible Wi-Fi/Bluetooth dongle list]] handles it. 
-  * Due to ambiguity with ''[L3]'' and ''[R3]'', mention "pushing in" when referring to pushing in the sticks. Eg. Then push in ''[L3]'' to switch mem-pak. +    * "RetroArch" is stylized by having capitals for both the beginning "R" and the "A" in "Arch". "RA" is not an acceptable abbreviation due to its ambiguity and should be avoided. 
-  * 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. +    * "libretro" is stylized by only using lower-case letters. An accepted abbreviation of libretro cores this "lr-<core name>", but try to use its full name especially when it's only mentioned once in the document. "lr" by itself is not an acceptable abbreviation due to ambiguity and lack of context, and should be avoided
-  * 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. +  * **Paths and file extensions** 
-  * Items selected from within menus should be enclosed in double-quotes ("). Eg. From **Audio**, select "HDMI1"+    * Paths to files/directories should always use path formatting. For example, ''/userdata/roms/psx/'', which is encoded as %%''/userdata/roms/psx/''%%. 
-  * Should you embed an image that you are not the owner of, put credits to the original work/licensing information in "less significant" wrap %%<wrap lo>%% (can be applied with the Wrap plugin button in the toolbar). For example, <wrap lo>Image illustrated by Wikimedia user [[https://commons.wikimedia.org/wiki/User:LucasVB|LucasVB]]. Licensed under [[https://creativecommons.org/licenses/by-sa/3.0/deed.en|Creative Commons]].</wrap>+    * 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 ''*.iso''
 +    * If using a path at the end of a sentence punctuation should still be used. For example, ''/userdata/roms/psx/''
 +  * **Button labels** 
 +    * Face buttons should use their graphical representation to avoid confusion, such as {{:wiki:south.png?nolink&20|South button (B SNES)}}. Refer to [[:batocera_wiki_code_snippets#graphical_elements|the Batocera-specific wiki syntax page]] on how to use it. 
 +    * Other buttons should use path formatting (%%enclosed in ''%%) so they aren't translated by the auto-translator, be capitalized as they appear on their printed label and be enclosed in square brackets within the path formatting to differentiate it from actual paths. For example, ''[START]'', which is coded as %%''[START]''%%. 
 +    * Shoulder buttons use their PlayStation format, such as ''[R1]'' and ''[L2]''. Refer to the first-tier shoulder buttons as buttons, and the second-tier triggers as triggers. 
 +    * Due to ambiguity with ''[L3]'' and ''[R3]'', mention "pushing in" when referring to pushing in the sticks. Eg. Then push in ''[L3]'' to switch mem-pak. 
 +    * 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 ''es_systems_<system name>.xml'' where ''<system name>'' is the name of the system you want to customize. 
 +    * 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 "HDMI1"
 +  * **Images** 
 +    * Should you embed an image that you are not the owner of, put credits to the original work/licensing information in "less significant" wrap %%<wrap lo>%% (can be applied with the Wrap plugin button in the toolbar). For example, <wrap lo>Image illustrated by Wikimedia user [[https://commons.wikimedia.org/wiki/User:LucasVB|LucasVB]]. Licensed under [[https://creativecommons.org/licenses/by-sa/3.0/deed.en|Creative Commons]].</wrap>
  
 ===== Tense, tone and formality ===== ===== Tense, tone and formality =====
Line 55: Line 73:
   * Avoid referring to the reader. If the word "you" is used then this is referring to the reader; try rephrasing the sentence to be less addressing. It is understandable if information becomes too hard to convey following this guideline (there's an example above, about embedded image crediting).   * Avoid referring to the reader. If the word "you" is used then this is referring to the reader; try rephrasing the sentence to be less addressing. It is understandable if information becomes too hard to convey following this guideline (there's an example above, about embedded image crediting).
   * Avoid unnecessary manners such as "please" and "thank you". Although it might seem rude, it usually just adds too much fluff.   * Avoid unnecessary manners such as "please" and "thank you". Although it might seem rude, it usually just adds too much fluff.
 +
 +===== New/renaming pages =====
 +
 +Renaming pages is highly discouraged. It should only be done in extreme cases where the original name fails to convey the content of the article. This is because search engines and links from external websites will break if the page name is changed. If absolutely sure that the rename is necessary, the page can be renamed with the "Rename page" button on the right-side toolbar (this will allow the wiki to update all the internal links to the new page automatically). A new page with the old page's name containing a link to the renamed page should be made to redirect search engines/old links.
 +
 +==== Managing the sidebar ====
 +
 +  * The sidebar appears on all pages so its length should always be taken into consideration. Up until recently, the sidebar was always fully expanded showing all pages, but now it is collapsed by default easing the requirements for this.
 +  * The sidebar currently has only one level of depth to it. More levels may be considered in the future, but for the moment stick with just using one level of depth. If you've added a very complicated topic with many pages to it, you may consider adding a whole new category for just it.
 +  * Pages linked to in the sidebar should use [[:batocera_wiki_code_snippets#in-links|internal links]] with the page's proper name as the display text. The page's proper name should use regular capitalization rules, not Camel Case like the page title is on the page itself.
 +  * If you've renamed a page or outright removed it, check the [[:sidebar|sidebar]] to see if any links have broken. If so, either link them to the new name of the page or if you have removed the page, remove the link.
 +  * Moving existing pages to other categories should be avoided, for consistent navigation, but if one category has become overloaded with too many pages it may be better to split that into multiple categories.
 +
 +Categories are split by a collapsible section and individual pages are in an unordered list. Here's a short example of a category:
 +
 +<code>
 +--> Getting Started#
 +  * [[:install_batocera|Install Batocera]]
 +  * [[:bios_files|BIOS files and how to add them]]
 +  * [[:add_games|Game ROMs and how to add them]]
 +
 +<--
 +</code>
 +
 +The sidebar syntax can be found on its section in the [[:batocera_wiki_code_snippets#adding_a_collapsible_section|Batocera Wiki code snippets page]].
 +
 +=== Adding your page to the sidebar =====
 +
 +If you've created a new page, the next job is to add a link to it to [[:sidebar|the sidebar page]]. You edit this page just like you would any other page.
 +
 +  * 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 [[:systems|systems overview page]] (as long as you've used the correct shortname) and doesn't need to be manually added.
 +  * Pages linked to in the sidebar should use [[:batocera_wiki_code_snippets#in-links|internal links]] with the page's proper name as the display text. The page's proper name should use regular capitalization rules, not Camel Case like the page title is on the page itself.
 +  * New pages should also be added to the appropriate section in the [[:navigation|navigation page]] along with a laconic description (if applicable). This is to assist those new to the wiki navigating to the appropriate page.
  
 ===== Individual elements ===== ===== Individual elements =====
Line 67: 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 ([[:choose_a_single_board_computer|this page]] for example).   * 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 ([[:choose_a_single_board_computer|this page]] for example).
 +  * 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 109: 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 115: 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 %%<code>%% keyword should always be on its own line for clarity.+  * The ''%%<code>%%'' keyword should always be on its own line for clarity.<code>With that said, if code is needed to be displayed in a bullet list, the first line must begin in the bullet point in the list item's line. 
 +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. 
 +</code> 
 +  * The only exception to ''%%<code>%%'' being in the middle of a line is if the list needs to continue afterward, as above. View this page's code for an example.
  
 ==== Path and commands ==== ==== Path and commands ====
Line 133: Line 192:
 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.
  
-===== Templates =====+==== Collapsible sections ====
  
-==== Batocera Themes Rules ==== +Should be avoided in most if not all casesCollapsible sections require the user to interact with the pagewhich may not be compatible with certain devicesbe difficult to employ, or seem amateurishWith that saidcollapsible sections can be used to organize inordinate amounts of necessary information that can be irrelevant to the user currently scanning through the pagesuch as all the topics available in the sidebar or a really large configuration file.
- +
-<code>|..THEMENAME..|..AUTHORNAME..|..{{ :themes:THEMNAME_system.png?300 |}}.. +
-{{ :themes:minimal_system.png?300 |}}            --> will view in media manager +
-{{ :themes:minimal_grid.png?nolink&300 |}}       --> no link to the original image +
-{{ :themes:minimal_list.png?direct&300 |}}       --> links to the full resolution +
- +
-Can't decide? Used the first option. +
- +
-Authorname [[ https://github.com/repro/project|AUTHORNAME ]] +
-</code> +
- +
-{{ :themes:minimal_system.png?300 |}} +
-{{ :themes:minimal_grid.png?nolink&300 |}} +
-{{ :themes:minimal_list.png?direct&300 |}} +
- +
-Some suggestions +
-  * Themename +
-  * Authorname +
-  * Link to author? (needed?) +
-  * System List View -> themename_system +
-  * ROM List View -> themename_list +
-  * GRID List View -> themename_grid +
-  * Resolution 1920x1080 +
- +
-==== EMULATOR HEAD PAGE ==== +
- +
-<WRAP center round box 100%> +
-{{ :wiki:dokuwiki-128.png?nolink&100 |}} +
- +
-====== DOKUWIKI-Dokumentation System ====== +
- +
-<csv> +
-EmulatorROM FolderExtensionBIOS, Config [and/or Savestates] +
-lr-lbrpdx, /userdata/roms/lbrpdx, .laladarknior.bin/userdata/saves/system/genetik.file +
-</csv> +
-</WRAP> +
- +
-<code> +
-{{ :emulators:system_logo.png?nolink&200 |}} +
- +
-======= SYSTEMNAME ======= +
- +
-<csv> +
-Emulator, ROM Folder, Extension, BIOS, Config [and/or Savestates] +
-lr-xxxx, /userdata/roms/yyyy, .zzz .xyz, biosfile.bin, /userdata/saves/system/config.file +
-</csv> +
-</code>+
  
 ===== If you're not quite sure ===== ===== If you're not quite sure =====
Line 188: Line 200:
 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.
  
-===== Adding to the sidebar =====+For making a new system page specifically, you can follow [[playground:systems:template|the system template in the playground]].
  
-If you've created a new page, the next job is to add a link to it to the sidebar. The sidebar should have the least amount of edits made to it as possible for consistent navigation, but if one category has become overloaded with too many pages it might be better to split that into multiple categories. 
- 
-Visit [[:sidebar|the sidebar page]] and edit it as you would any other page. Categories are split by level four headers (three equal signs) and individual pages are in an unordered list (asterisks). 
- 
-<code> 
-=== Getting Started === 
-  * [[install_batocera|Install Batocera]] 
-  * [[bios_files|BIOS files and how to add them]] 
-  * [[add_games|Game ROMs and how to add them]] 
-</code> 
  • wiki/wiki-editing-practices.1632045913.txt.gz
  • Last modified: 3 years ago
  • by atari