Wiki style guidelines - Revision history

Plebeian9000: add guideline on commercial links

2021-02-10T18:52:46Z

add guideline on commercial links

Plebeian9000 at 17:31, 17 June 2020

2020-06-17T17:31:48Z

Plebeian9000: add conventions on admonitions and transclusions

2020-06-17T17:27:38Z

add conventions on admonitions and transclusions

Plebeian9000: clarify conventions for images

2020-06-17T16:26:15Z

clarify conventions for images

Plebeian9000: add: avoid using abbreviations in page titles

2020-06-05T22:16:53Z

add: avoid using abbreviations in page titles

Plebeian9000: specify that image conventions are intended for full bisq screenshots

2020-06-03T19:08:26Z

specify that image conventions are intended for full bisq screenshots

Plebeian9000: add/edit style guidelines

2020-06-03T18:44:48Z

add/edit style guidelines

Kemccall at 05:59, 14 April 2020

2020-04-14T05:59:32Z

Plebeian9000: /* Non English language articles */

2020-04-01T19:18:57Z

Non English language articles

Plebeian9000 at 19:17, 1 April 2020

2020-04-01T19:17:12Z

← Older revision		Revision as of 18:52, 10 February 2021
Line 81:		Line 81:

	Use gerunds for page titles (e.g., "Switch'''ing''' data directories" instead of "Switch data directory" and "Updat'''ing''' trade fees" instead of "Update trade fees").		Use gerunds for page titles (e.g., "Switch'''ing''' data directories" instead of "Switch data directory" and "Updat'''ing''' trade fees" instead of "Update trade fees").
		+
		+	=== Avoid commercial links ===
		+
		+	Links to promote other businesses or products should be avoided. Exceptions may be made on a case-by-case basis upon discussion with other contributors.

@@ Line 35: / Line 35: @@
 === Prefer wiki headings over plain bold text ===
-Wiki headings appear in the table of contents, but other text doesn't, so it's better to use headings for big ideas—users can simply scan the table of contents for an article and quickly get an idea of what it covers. This tends to be particularly helpful when writing processes, but is good as a general guideline too.
+Wiki headings appear in the table of contents, but other text doesn't, so it's better to use headings for big ideas. Furthermore, wiki headings have their own anchor links, making it possible to link directly to particular sections of a page.
 === Use code blocks for UI elements ===

@@ Line 18: / Line 18: @@
 In case an article doesn't automatically include a table of contents, please add one after the introductory text with <code><nowiki>__TOC__</nowiki></code>.
 === Avoid using abbreviations in page titles ===
@@ Line 42: / Line 52: @@
 === Use consistent markup for images ===
-Please try to use the following conventions:
+Please try to use the following conventions where appropriate:
 * Use <code>thumb</code> format
 * Align left
@@ Line 55: / Line 65: @@
 * Use [[images/9/99/Arrow-screenshot.png|this arrow]]
 * Make any markup 6px wide in the <code>#ff0000</code> color
 === Use gerunds for page titles ===
 Use gerunds for page titles (e.g., "Switch'''ing''' data directories" instead of "Switch data directory" and "Updat'''ing''' trade fees" instead of "Update trade fees").

@@ Line 42: / Line 42: @@
 === Use consistent markup for images ===
-For including a screenshot of the full Bisq window in an article, please try to use the following conventions:
+Please try to use the following conventions:
 * Use <code>thumb</code> format
 * Align left
@@ Line 52: / Line 52: @@
 <code><nowiki>[[File:Find-wallet-seed-words.png|thumb|left|600px|Location of wallet seed words and date.]]</nowiki></code>
-It would be extra nice (but not required) to use the following conventions for marking images:
+It would be extra nice (but not required) to use the following conventions for '''marking''' images:
 * Use [[images/9/99/Arrow-screenshot.png|this arrow]]
 * Make any markup 6px wide in the <code>#ff0000</code> color

← Older revision		Revision as of 22:16, 5 June 2020
Line 18:		Line 18:

	In case an article doesn't automatically include a table of contents, please add one after the introductory text with <code><nowiki>__TOC__</nowiki></code>.		In case an article doesn't automatically include a table of contents, please add one after the introductory text with <code><nowiki>__TOC__</nowiki></code>.
		+
		+	=== Avoid using abbreviations in page titles ===
		+
		+	Prefer "Deposit transaction" over "Deposit tx".

	=== Prefer wiki headings over plain bold text ===		=== Prefer wiki headings over plain bold text ===

@@ Line 29: / Line 29: @@
 === Make software screenshots aesthetically consistent ===
-For screenshots of Bisq, please try to make sure:
+For full screenshots of Bisq, please try to make sure:
 * Bisq is at the original window size
 * Bisq is in light mode
@@ Line 38: / Line 38: @@
 === Use consistent markup for images ===
-For including an image in an article, please try to use the following conventions:
+For including a screenshot of the full Bisq window in an article, please try to use the following conventions:
 * Use <code>thumb</code> format
 * Align left

@@ Line 1: / Line 1: @@
 __TOC__
-== General guidelines ==
+== Structure of the wiki ==
-There are three general types of information that almost every form of information can be segregated into:
+There are three general categories that can be applied to almost every article:
 * Concepts
-* Tasks (procedures)
+* Procedures/Use Cases
 * References
-For clarity it is best that these three types of information not be intermingled. For example, you do not want to step through a lengthy task to find a file name, nor would you want to search for a file name in a description of a feature.
+Please keep articles in one of these distinct categories. For example, there's the ''concept'' of a [[data directory]] and a ''use-case'' of [[Switching_to_a_new_data_directory|switching to a new data directory]]. Each item should have its own article.
-An example of a good procedure is [https://bisq.wiki/Backing_up_your_wallet Backing up your wallet]. It has a title with a gerund (Back'''ing'''), and a brief conceptual introduction followed by a step-by-step task.
+These conventions will help screenshots appear more aesthetically consistent across the wiki.
-==Style guide references==
+=== Use consistent markup for images ===
-* [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style <big>Wikipedia Manual of Style</big>]
+For including an image in an article, please try to use the following conventions:
-* [http://en.wikipedia.org/wiki/Wikipedia:Images <big>Wikipedia Images</big>]
+* Use <code>thumb</code> format
-* [http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet <big>Wikipedia editing Cheatsheet</big>]
+* Align left
-== Exceptions from Wikipedia ==
+Example:
-=== Procedures  ===
+<code><nowiki>[[File:Find-wallet-seed-words.png|thumb|left|600px|Location of wallet seed words and date.]]</nowiki></code>
-====Procedure titles====
+It would be extra nice (but not required) to use the following conventions for marking images:
-Use gerunds (. . . ing) for procedural titles. For example, "Back up your wallet" should be "Back'''ing''' up your wallet". Using a gerund implies you will be performing a process.
+* Use [[images/9/99/Arrow-screenshot.png|this arrow]]
-=== Tabs, buttons and UI elements ===
+=== Use gerunds for page titles ===
-===Describing UI elements===
+Use gerunds for page titles (e.g., "Switch'''ing''' data directories" instead of "Switch data directory" and "Updat'''ing''' trade fees" instead of "Update trade fees").

← Older revision		Revision as of 05:59, 14 April 2020
Line 19:		Line 19:

	== Exceptions from Wikipedia ==		== Exceptions from Wikipedia ==
−
−	~~=== Non-English language articles ===~~
−	~~Until there is a need for separate language wikis, create articles in the non English language with the English translation in comments. See [[Running Bisq in China]] as an example.~~

	=== Procedures ===		=== Procedures ===

@@ Line 20: / Line 20: @@
 == Exceptions from Wikipedia ==
-=== Non English language articles  ===
+=== Non-English language articles  ===
 Until there is a need for separate language wikis, create articles in the non English language with the English translation in comments. See [[Running Bisq in China]] as an example.

@@ Line 12: / Line 12: @@
 ==Style guide references==
-The Bisq wiki adheres to the Wikipedia Manual of Style whenever possible. There are some styles that Wikipedia does not cover.They are documented in '''Exceptions from Wikipedia''' below.
+The Bisq wiki adheres to the Wikipedia Manual of Style whenever possible. There are some styles that Wikipedia does not cover. They are documented in '''Exceptions from Wikipedia''' below.
 * [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style <big>Wikipedia Manual of Style</big>]