Contribute to Wiki

Make sure you read this document and understand it. Without following some rules, Wiki quickly becomes a pile of chaos. Let's avoid that from the start.

This Wiki doesn't necessarily need to be strictly about Particl. General crypto/privacy/security tricks (like “how to generate strong passwords”, “how to securely store seeds” etc.) might catch some more traffic and promote PART further (win-win :)

To contribute to this wiki, you'll first need an account. Account registrations aren't possible at the moment, so if you would like to write new content or translate existing pages to your language, please contact Allien – preferably on Riot @allien:matrix.org or Discord Allien#4191.

Keep in mind that getting an account means reading these guidelines (on this page) and understanding them. You won't get access to editing wiki content otherwise, as a measure to prevent vandalism and poorly-formatted content mess.

Namespaces

This wiki is separated to few content “categories” (“namespaces” in Dokuwiki language) for easier browsing.

Each page should have its namespace assigned. Namespace comes before page name + with colon. So instead of page staking (old), we would create tutorial:staking.
  • learn: informative articles explaining/describing various topics and Particl's features (for example learn:staking page for introducing staking feature, how it works etc.)
  • tutorial: guides & howtos on different topics, user-friendly with screenshots etc. (for example tutorial:staking which guides user on how to stake) – these articles as usually shorter, containing only information about how to achieve XYZ – if you need to explain features, link to related “Learn” page
  • support: fixing common issues & common answers, FAQ
  • dev: technical documentation for devs, not very interesting for normal users (how to develop on Particl, API overview etc.)

Namespaces are also visible in URL and help categorize the content. Our Staking tutorial page (from example above) will look like this:

https://particl.wiki/tutorial/staking

Using this, we can build this Wiki with hierarchy, which makes sense in our case.

Tags

All the content on these pages is further inter-connected via sidebars and “tags” in footer (as you know from Wikipedia).

Check Useful snippets below on how to use tags – please don't create new tags unless absolutely necessary and don't overuse them. Each page should have 3 tags max, but more common is only 1-2 tags per page (don't include a tag, just because it was mentioned in one sentence).

If you're not sure how to categorize your new page, either ask one of the admins or supply the content only, admins will later categorize it themselves.
This wiki supports both Markdown and MediaWiki syntax. Markdown is our preferred way of formatting, so please don't use MediaWiki syntax at all. See Useful snippets section below for details on formatting.

However, when you'd like to format some text inside another block (for example bold text in quote), Markdown might not work there. That's because we use some plugins that aren't exactly compatible with Markdown formatting – only in those cases is formatting with MediaWiki syntax allowed.

Page names

Related to that, it's important to think about each page's name/URL. When creating new pages, keep it's name short, intuitive and memorizable. This will be best illustrated by examples from our former Wiki – for purposes of saving space, the first part of URL (ie: https://particl.wiki/) has been stripped:

Good examples

  • /pools
  • /tutorials

Bad examples

  • /faq_overview (“overview” absolutely unnecessary)
  • /socialmedia-channels (could be just “socials”)
  • /listed-on-exchanges (“exchanges” is enough)

Formatting

  • Use headings to properly structure the text
    • make sure they are short and make sense when used as automatically generated URL (example: “Staking” title of page with “On Particl Desktop” as 2nd-level heading will result in: particl.wiki/staking#on-particl-desktop)
  • More smaller paragraphs are better than big ones (increases readability)
  • Format your text, but don't overdo it (as mentioned above, format text using Markdown only!)

Page structure

Each page should start with level 1 heading, followed by brief, one sentence summary for the page, wrapped in <lead> tags:

# Heading (page name)

<lead>
This page is about this and that, it will blow your mind
</lead>

After that, high-level overview paragraph of the page should follow. Then the page should be split into different sections, each with its own subheading (level 2: ## Subheading).

At the bottom, after all page's content, you should define page's tags and list related pages – see Useful snippets > Tags and Related pages below.

Media

Name your media files descriptively!

Media files are also indexed by search engines (by their names, duh!), so describing their contents in their names helps – also when managing them via Media Manager in this wiki. After all, who wants to scroll through dozens of “Screenshot-02.png” to find the one they need? :)

Local links (pointing to other pages on this wiki) should always follow this format: "namespace:page-name" (let's call it "Page ID")

If you're unsure about Page's ID, navigate to the page you want to link to and check it's blue “tag” in the upper right corner.

For example this page's ID is wiki:contribute, so you would link to it like this:

[Check out contributing guidelines](wiki:contribute)
DO NOT link to full page's URL (= links containing the whole path like https://particl.wiki/xxx)! That link will be treated as external/outgoing (pointing outside of this wiki) and will be formatted like so. Don't cofuse the users – our former wiki was full of links like that.

Basics

- **Bold text**
- _Italics_
- [Link text](wiki:contribute)

Columns

3 columns in this example. For only 2, replace third with half (and include obviously only 2 blocks):

1st column

2nd column

3rd column

<block group>

<block third column>
1st column
</block>

<block third column>
2nd column
</block>

<block third column>
3rd column
</block>

</block>

Tags

Tag pages at the bottom (underneath the content). Tags are separated with space. Tags with more than 1 word are wrapped “in quotes”:

{{tag>example "multiple words"}}

To link to all pages tagged with some tag, use the following link (using privacy tag as an example):

privacy

[privacy](?do=showtag&tag=privacy)

If a page is tagged with popular tag, we should display related pages. All used/popular tags should be added.

Be sure to update tags in {{topic.. line! Multiple tags are again separated with space. In contrast to assigning tags to a page (above), multi-word tags here are connected with underscore: _ (not wrapped in quotes)

<well size="sm">
=== Related pages ===
{{topic>example multiple_words}}
</well>

Callouts

This is an info callout, just so we're all on the same page :)

There are many types of callouts – just replace the “type” attribute: info, tip, warning, alert. Always keep showing the icon via icon="true". Highlighting the most important part of a callout with bold text is a nice addition.

Callout docs

<callout type="info" icon="true">
**This is an info callout**, just so we're all on the same page :)
</callout>

Buttons

Buttons can exist as many types: default, primary, success, info, warning and danger. Optionally, they can include icons as well (see icon gallery for available icons).

Button docs

Particl Github Particl Downloads Learn Tutorial Support Dev

<btn type="default" icon="fa fa-book">[[https://github.com/particl|Particl Github]]</btn>
<btn type="primary" icon="fa fa-download">[[https://particl.io/downloads|Particl Downloads]]</btn>
<btn type="success">[[https://particl.wiki/learn|Learn]]</btn>
<btn type="info">[[https://particl.wiki/tutorial|Tutorial]]</btn>
<btn type="warning">[[https://particl.wiki/support|Support]]</btn>
<btn type="danger">[[https://particl.wiki/dev|Dev]]</btn>

List groups

Useful for listing related links etc., as seen on the top-level sections (Learn, Tutorials, Support..). Also optionally supports descriptions and/or icons. Don't overuse these.

List groups docs

<list-group>
  * [Learn](learn:) \\ Discover all awesome features of Particl
  * {{fa>book}} [Tutorials](tutorial:)
  * [Support](support:)
</list-group>

Tabs

Usually used to separate instructions for different OSes. Replace all instances of something with name related to the content (like install-win, install-mac etc.) – these IDs need to be unique, so that more tab groups on one page will work.

Tab docs

Windows

macOS

Linux

<tabs>
  * {{fa>windows?fw}} [[#something-win|Windows]]
  * {{fa>apple?fw}} [[#something-macos|macOS]]
  * {{fa>linux?fw}} [[#something-linux|Linux]]
 
<pane id="something-win">
=== Windows ===
...
</pane>
 
<pane id="something-macos">
=== macOS ===
...
</pane>

<pane id="something-linux">
=== Linux ===
...
</pane>
 
</tabs>

Icons

This wiki uses Font Awesome icons. Visit its icon gallery to search for icon codes. Unfortunately the plugin we use has outdated version of Font Awesome, so not all icons in icon gallery linked above are available to us.

{{fa>windows?fw}}

Labels

Labels can be quite useful for smaller highlights and emphasis.

Label docs

default primary success info warning danger

<label type="default">default</label>
<label type="primary">primary</label>
<label type="success">success</label>
<label type="info">info</label>
<label type="warning">warning</label>
<label type="danger">danger</label>
  • wiki/contribute.txt
  • Last modified: 2019/08/15 18:14
  • by allien