Help:Style guide

From Void Linux Wiki
Jump to: navigation, search

Some tips to keep a common style and guidance for writing documentation here. Feel free to discuss in the talk page.

Common style

Section headings

Section headings should start at == size, then go down from there, e.g.

== Section 1 ==
...
=== Section 1.1 ===
...
== Section 2 ==
...
=== Section 2.1 ===
...
==== Section 2.1.1 ====
...

Very rarely you will want to start at = (largest) size.

Categories

  • Unless an article is linked from the main page and isn't necessary anywhere else, it should probably belong in a category.
  • Categories are to be specified at the bottom of articles, one per line. The top should be left for managing TOCs or specifying templates, categories only add clutter here.

External links

If you want to specify "See also"-style links at the bottom of the article, please do so under a "See also" section when pointing to other articles in this wiki, or under "External links" if you are pointing the reader to external sources.

For external links in general please do not just quote the bare URL but give it a name instead, e.g. instead of

For more info please see http://www.example.org/blah

use something like

For more info please see [http://www.example.org/blah this page]

which looks better and still lets the user know where the link is pointing to.

Sample commands and file contents

Sample commands that require root privileges should be introduced with either # or $ sudo. One liners can be specified by simply adding a blank in front, whereas for more complex content you probably want to use <pre>...</pre>. Examples:

(blank)# xbps-install -S package
(blank)$ sudo xbps-install -S package
<pre>
Some command or file content

Another line (or paragraph) that would be displayed in a separate box unless preformatted text is enforced
</pre>

produce

# xbps-install -S package
$ sudo xbps-install -S package
Some command or file content

Another line (or paragraph) that would be displayed in a separate box unless preformatted text is enforced

Where exactly to put an article

If an article is, say, 50 lines long or more, it probably should be a guide and be categorized as such. Shorter articles may or may not be suitable to be added to the FAQ, it is up to you to decide.

The DO's and DONT's of this wiki

As a general rule, please do not copy&paste from external sources.
Copying articles verbatim from long-established sources such as ArchWiki may feel tempting and the results may look great at first, but it adds information that is likely to become obsolete pretty quickly, without nobody to maintain it or update it properly, and that assuming that the information is valid for Void Linux in the first place and it doesn't contradict official documentation, either here or elsewhere in the Void Linux ecosystem. Articles in this wiki should get newcomers on the right track and provide solutions to specific issues. Do not reinvent the wheel by writing/pasting generic information that may easily found elsewhere, maybe even from upstream sources who already take care of ensuring currentness.
See also the About page.