Difference between revisions of "Wiki style guidelines"

From Bisq Wiki
Jump to navigation Jump to search
(add/edit style guidelines)
Line 1: Line 1:
 +
Generally the Bisq wiki follows the [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style Wikipedia Manual of Style] and conventions from other established wikis like the [https://en.bitcoin.it/wiki/Main_Page Bitcoin Wiki].
 +
 +
See exceptions and additions below.
 +
 
__TOC__
 
__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
 
* Concepts
* Tasks (procedures)
+
* Procedures/Use Cases
 
* References
 
* 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.
 +
 
 +
== Conventions ==
 +
 
 +
=== Add a table of contents wherever possible ===
 +
 
 +
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>.
 +
 
 +
=== 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.
 +
 
 +
=== Use code blocks for UI elements ===
 +
 
 +
Denote user interface (UI) elements like tabs and buttons with literal markup (e.g., Click <code>Start</code>). Markup for this styling is <code><nowiki><code></code></nowiki></code>.
 +
 
 +
=== Make software screenshots aesthetically consistent ===
 +
 
 +
For screenshots of Bisq, please try to make sure:
 +
* Bisq is at the original window size
 +
* Bisq is in light mode
 +
* Don't include your operating system's window border
  
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 ===
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>]
+
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
 +
* Make 600px wide
 +
* Add a concise caption
  
== 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>
The Bisq wiki contains many procedures. The Wikipedia Manual of Styles does not include styles for technical tasks and procedures therefore the Microsoft style guide has excellent guidance for  [https://docs.microsoft.com/en-us/style-guide/procedures-instructions/writing-step-by-step-instructions Writing step-by-step instructions].
 
  
====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]]
 +
* Make any markup 6px wide in the <code>#ff0000</code> color
  
=== Tabs, buttons and UI elements ===
+
=== Use gerunds for page titles ===
User interface (UI) elements such as tabs and buttons are indicated in '''bold''' text.
 
  
===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").
When referring to a user action, simply state "click '''Start'''", it is not necessary to state "click the '''Start''' button".
 

Revision as of 18:44, 3 June 2020

Generally the Bisq wiki follows the Wikipedia Manual of Style and conventions from other established wikis like the Bitcoin Wiki.

See exceptions and additions below.

Structure of the wiki

There are three general categories that can be applied to almost every article:

  • Concepts
  • Procedures/Use Cases
  • References

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. Each item should have its own article.

Conventions

Add a table of contents wherever possible

In case an article doesn't automatically include a table of contents, please add one after the introductory text with __TOC__.

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.

Use code blocks for UI elements

Denote user interface (UI) elements like tabs and buttons with literal markup (e.g., Click Start). Markup for this styling is <code></code>.

Make software screenshots aesthetically consistent

For screenshots of Bisq, please try to make sure:

  • Bisq is at the original window size
  • Bisq is in light mode
  • Don't include your operating system's window border

These conventions will help screenshots appear more aesthetically consistent across the wiki.

Use consistent markup for images

For including an image in an article, please try to use the following conventions:

  • Use thumb format
  • Align left
  • Make 600px wide
  • Add a concise caption

Example:

[[File:Find-wallet-seed-words.png|thumb|left|600px|Location of wallet seed words and date.]]

It would be extra nice (but not required) to use the following conventions for marking images:

  • Use this arrow
  • Make any markup 6px wide in the #ff0000 color

Use gerunds for page titles

Use gerunds for page titles (e.g., "Switching data directories" instead of "Switch data directory" and "Updating trade fees" instead of "Update trade fees").