Difference between revisions of "Wiki style guidelines"

From Bisq Wiki
Jump to navigation Jump to search
(add guideline on commercial links)
 
(42 intermediate revisions by 3 users not shown)
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__
−
== Bisq Style Guide ==
 
−
The Bisq wiki adheres to the Wikipedia Manual of Style whenever possible. ([https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style reference])<br>
 
  
−
Where Wikipedia does not have an appropriate style it is noted 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|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>.
 +
 
 +
=== Avoid repetition ===
 +
 
 +
The wiki is a huge, growing repository of knowledge that will require much time to maintain. Please avoid replicating content in more than one place—it makes keeping the wiki up-to-date harder.
 +
 
 +
If you do find the need to repeat something, use a [https://www.mediawiki.org/wiki/Transclusion transclusion].
 +
 
 +
Practically, this is how it works:
 +
* Create a new page titled <code>Template:Content_to_be_replicated</code>.
 +
* Include <code><nowiki>{{Content_to_be_replicated}}</nowiki></code> anywhere you need it.
 +
 
 +
=== Avoid using abbreviations in page titles ===
 +
 
 +
Prefer "Deposit transaction" over "Deposit tx".
 +
 
 +
=== 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. 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 ===
 +
 
 +
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 full 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 ===
 +
 
 +
Please try to use the following conventions where appropriate:
 +
* Use <code>thumb</code> format
 +
* Align left
 +
* Make 600px wide
 +
* Add a concise caption
 +
 
 +
Example:
 +
 
 +
<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:
 +
* Use [[images/9/99/Arrow-screenshot.png|this arrow]]
 +
* Make any markup 6px wide in the <code>#ff0000</code> color
 +
 
 +
=== Use admonition blocks for stand-out warnings and notes ===
 +
 
 +
Use <code>Template:Admonition_Warn</code> for warnings and <code>Template:Admonition_Note</code> for notes. Both templates take arguments.
 +
 
 +
So this markup:
 +
 
 +
<nowiki>{{Admonition_Warn|Avoid this! It might cause an explosion.}}</nowiki>
 +
 
 +
Results in this output:
 +
 
 +
{{Admonition_Warn|Avoid this! It might cause an explosion.}}
 +
 
 +
=== 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").
 +
 
 +
=== Avoid commercial links ===
  
−
=== Non English language articles  ===
+
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.
−
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.
 

Latest revision as of 18:52, 10 February 2021

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__.

Avoid repetition

The wiki is a huge, growing repository of knowledge that will require much time to maintain. Please avoid replicating content in more than one place—it makes keeping the wiki up-to-date harder.

If you do find the need to repeat something, use a transclusion.

Practically, this is how it works:

  • Create a new page titled Template:Content_to_be_replicated.
  • Include {{Content_to_be_replicated}} anywhere you need it.

Avoid using abbreviations in page titles

Prefer "Deposit transaction" over "Deposit tx".

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. 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

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 full 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

Please try to use the following conventions where appropriate:

  • 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 admonition blocks for stand-out warnings and notes

Use Template:Admonition_Warn for warnings and Template:Admonition_Note for notes. Both templates take arguments.

So this markup: 

{{Admonition_Warn|Avoid this! It might cause an explosion.}}

Results in this output:

Warn
 Avoid this! It might cause an explosion.

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").

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.

Retrieved from "https://bisq.wiki/index.php?title=Wiki_style_guidelines&oldid=2045"