Help:Wiki editor's guide/Wiki rules and style guide

To keep things running smoothly on the wiki, it's important to be respectful in our own way, but also note these conduct rules exist, and can be referenced in doubt. Also keep the wiki style guidelines in mind to keep a semi-coherent style going throughout this wiki.

Wiki conduct

Although not specifically for this wiki, the Nura Code of Conduct applies to all Nura projects and infrastructure, including the wiki.

Being respectful

First priority is respect for other editors, everything else can wait. Which means:

Being mindful with word choice (boring is often better), as different cultures have different interpretations; for example, in discussion pages and edit summaries.
Knowing that feedback is more welcome when it is constructive.
Not asserting your own changes while ignoring voiced concerns. When there are clashing opinions, see below.

Reaching consensus on edits

In case of disagreement, one should either:

Make their own change to improve the edit, or
Revert the change, though this should only be done if necessary (e.g. vandalism or other disruptive edits).

When reverting, add an explanation in the edit summary.

In most cases, consensus naturally emerges. This is because when nobody objects to a change, it is assumed that consensus has been reached.

But sometimes in larger edits a discussion is needed to reach consensus. As opposed to most wikis where discussion takes place on talk pages, on the Nura wiki they take place in:

The #Nura-wiki channel (#wiki:nura.eco (on Matrix) / #postmarketos-wiki (on OFTC, Webchat)) - for quick communication and discussion;
The Nura/wiki repository issue tracker for longer discussions and gathering feedback.

Undesired content

If a text feels like casual notes, like personal experiences and tweaks, dogfooding efforts, etc. they should go on the user (sub)page, unless it could genuinely benefit a large portion of users users.

The writing must must also be from yourself. This means avoiding:

AI/LLMs assisted writing. These tools are known to make non-obvious mistakes, especially in subjects as niche as what the Nura wiki covers, and places verifying LLM-sourced information as an additional burden on other wiki editors.

Also see the Nura AI policy.

Plagiarism. Copy-pasting from a copyrighted 3rd party source infringes on the rights of the author, and should thus be avoided.

Should I just make an edit, or make a draft/wiki issue first?

In most cases, there is no reason to just edit/create the page directly. The wiki is, by its nature, a constant work-in-progress. A partial page is better than no page at all.

In a couple of scenarios a draft might be a better choice, like when the page:

Is going to take too long to finish editing in one sitting.
Was already a reasonably complete page.
Is linked from the Main Page, and/or is highly used.
Is a popular template, such as one of the infobox templates like Template:Infobox device).
Is write-protected, which means a wiki admin needs to apply the change.
Has an issue/inaccuracy, but you're not sure how to fix it yourself.

For a guide on making draft pages, see Help:Wiki editor's guide#Creating a draft.

Style guide

This wiki is meant to be readable for everyone who uses Nura, whether they are novices or experienced users. The only base assumption is that they are familiar with basic Linux shell commands like ls, cd, cp, mv and similar.

Besides this, there are no assumptions about the reader's abilities.

Practicality

And in order to keep the pages useful for our users, one should avoid:

Adding unclear, untested, and possibly incorrect examples. This includes "it's possible but you shouldn't do it" and other kinds of non-useful examples.
Writing very casually, like using jokes, expressions or sarcasm. Also avoid making cultural references, because the wiki targets a global audience, and the references may not be clear to all readers.
Using this wiki to voice their own opinion, with the exception of the user page.

Layout

All pages should include:

A short summary or introduction describing the subject at the start.
A short "See also" section at the end, with relevant links to other wiki pages or external sources.

Titles & headings

Headings and subheadings should be used to separate out relevant parts of a page. When using them, make sure to avoid:

Title case. Instead we use sentence case, for example: "Mainlining guide", and not "Mainlining Guide". Device page titles and chipset pages do not apply to this.

Skipping levels when placing headings.
Putting a heading right under the main title.
Using heading level 1 (= Title =).
Heading level 4 (==== text ====). There are exceptions, but never use level 5 and below.

If you're at level 4 , it might be best to re-consider how you split your higher-level sections.

Paragraphs

To make useful and readable paragraphs, generally avoid:

Making them extremely short (only a few words).
Ending them in the middle of a sentence.
Making sections longer than ~8 paragraphs.

Duplicated work

Duplicating content from other pages isn't very useful. When possible, link to the other page instead.

This means you shouldn't be transcluding full pages. Because this often causes an illogical introduction to another, clearly separate article, right after main page introduction.
For guide pages duplicating work is mostly fine, because users are likely to look for common info (e.g. troubleshooting steps at the end of Installation subpages); in those cases, make a separate section, and use the {{See also|...} template to point to the relevant full page.

Typography and writing style

There is no specific variety of English enforced, even within a single page.
- When choosing words, use the most commonly used ones when possible.
Avoid directly addressing the reader as "you". Try to use passive voice when possible.

Tutorial style pages (see #Guide pages section below) are exempt from this rule.

Use non-repeating language, for example, write "Use pmbootstrap to..." and not "Use the pmbootstrap command to..."). Make sure however, that the formatting (in this case it's formatted as code) makes up for the lack of context.
For bullet lists, a common style is to make subject part bold and place a dash ("-") after it, for example:
- samsung-a5.img.xz - main rootfs image
- samsung-a5-boot.img.xz - Android boot partition

Wiki markup usage

Use internal links to wiki pages ([[Page]]). Do not use external links ([https://wiki.nura.eco/wiki/Page]).
- Linking to sections is possible with internal links ([[Page#Section name]]).
Commands meant to be executed by a regular user are prefixed with $, and commands meant to be executed with root permissions with #:
Use the <syntaxhighlight> tag to add syntax highlighting to pieces of code. See also: SyntaxHighlight documentation and the list of supported languages.

When showing commands to run, use lang="shell-session":

$ whoami # Example user command
This is preferred because colors make things more readable.

The <code> tag can still be used for a short command that are put into a statement, like "You can use command to do X").

Using Note, Warning, Hint and similar templates

Use templates like {{Note}}, {{Warning}} or {{Hint}}:

If the text within is secondary to the subject at hand (for example, "Feel free to join our Matrix channel" at the top of Installation);
If the operation described ahead is potentially destructive (for example, if the operation could cause data loss).

As these elements have colored backgrounds and are generally prominent, they should be used sparsely. Too many note boxes are distracting, and may cause the reader to skip over sections to get to the raised content.

The best place to put one of these templates is either at the top of the page, at the top of a section or at the bottom of a section. While there are valid cases where one of these templates can go in the middle of a section, it may also be a hint that you need to re-think the page layout.

Subpages

One should consider making a subpage when:

One section of a page takes up a large part (~40% or more) of the main page.
A section is not directly related to the main page's content, but is still relevant to it.

Also make sure to:

Leave an introduction next to the link to the subpage to make it clear what the the subpage is about.
Not make them too short, like less than 4 paragraphs. When there are too many subpages, the reader will be struggling to find the information they're looking for.

Guide pages

Guide pages are pages that contain step by step guides for various processes. Examples of such pages include the Installation page and its subpages, as well as the Porting to a new device page.

Not every page with instructions is a guide page - for instance, the page for an interface (e.g. Phosh) may contain instructions on how to do things in the interface, but isn't a step-by-step, start-to-finish guide.

There are some additional considerations to make when writing guide pages:

Start with a short introductory paragraph about the subject of the page. Here you can also briefly summarize the steps of the guide.
Particularly long guides can be split into a few subpages. If you have more than one subpage, you can use {{PrevNext|(previous)|(next)}} to create navigation buttons between subpages.
You can occasionally use bold or italic to emphasize a word or part of a sentence. Think about the flow of reading, and make sure the reader's attention is guided through the different points to minimize missed elements.
- At the same time, try not to overuse bold or italic formatting, because then it loses its importance.
Create sections for each big step within the guide.
- Start each section with a brief explanation of the step. For example, if you tell the user to run a command, tell them what it does and why it's necessary to run.