Difference between revisions of "Wiki style guidelines"
Plebeian9000 (talk | contribs) (clarify conventions for images) |
Plebeian9000 (talk | contribs) (add conventions on admonitions and transclusions) |
||
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 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 === | === Avoid using abbreviations in page titles === | ||
Line 42: | Line 52: | ||
=== Use consistent markup for images === | === 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 | * Use <code>thumb</code> format | ||
* Align left | * Align left | ||
Line 55: | Line 65: | ||
* Use [[images/9/99/Arrow-screenshot.png|this arrow]] | * Use [[images/9/99/Arrow-screenshot.png|this arrow]] | ||
* Make any markup 6px wide in the <code>#ff0000</code> color | * 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 === | ||
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"). |
Revision as of 17:27, 17 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.
Contents
- 1 Structure of the wiki
- 2 Conventions
- 2.1 Add a table of contents wherever possible
- 2.2 Avoid repetition
- 2.3 Avoid using abbreviations in page titles
- 2.4 Prefer wiki headings over plain bold text
- 2.5 Use code blocks for UI elements
- 2.6 Make software screenshots aesthetically consistent
- 2.7 Use consistent markup for images
- 2.8 Use admonition blocks for stand-out warnings and notes
- 2.9 Use gerunds for page titles
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—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 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:
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").