Help:Wiki editor's guide/Wiki rules and style guide
To keep things running smoothly on the wiki and ensure consistency, it's important to keep some rules and style guidelines in mind.
Wiki rules
- Treat other editors with respect. Do not engage in edit wars, try to discuss in case of disagreements (see #Reaching consensus on edits), don't insult other editors in your edit summaries.
- Feedback is welcome, so long as it is constructive.
- The wiki is not a blog. Your personal notes - tweaks you made, dogfooding efforts, etc. - should go on your user page (or a subpage of your user page), unless you feel like they could be of interest to a larger group of users.
- Avoid using AI/LLMs to write wiki content - they are known to make mistakes and give incorrect advice, and the references they provide can't always be trusted.
- Using LLMs for translation or grammar fixups is OK, but please verify that the resulting information is correct (e.g. by translating it back) and that the writing style matches the style guide.
Additionally, the postmarketOS Code of Conduct applies to all postmarketOS projects and infrastructure, including the wiki.
Should I just make an edit, or make a draft/wiki issue first?
In most cases, you should just make the 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.
Consider making a draft or wiki issue first if:
- The edit is large and you can't finish it all at once;
- You're rewriting a page that wasn't previously empty/mostly empty;
- You're rewriting a page that is popular (i.e. anything linked from the Main Page);
- You're editing a template that is used by a large amount of pages (e.g. the various Note templates or infobox templates like Template:Infobox device);
- You want to edit a page that is write-protected; in those cases, a wiki admin needs to apply the change for you.
- You've found an issue/inaccuracy on the page, 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.
Reaching consensus on edits
In most cases, consensus should emerge naturally - it is assumed that if a page is changed and nobody objects to the change, that consensus has been reached.
If you disagree with another editor's change, you can:
- Make your 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).
- If you revert a change, make sure to explain your reasoning in the change summary.
Sometimes, especially for larger edits, a discussion is needed to reach consensus. As opposed to most wikis where discussion takes place on talk pages, on the postmarketOS wiki discussions take place in two places:
- The #postmarketOS-wiki channel (#wiki:postmarketos.org (on Matrix) / #postmarketos-wiki (on OFTC)) - for quick communication and discussion;
- The postmarketOS/wiki repository issue tracker for longer discussions and gathering feedback.
Style guide
This section contains some general pointers for writing clear and consistent wiki pages.
Things to keep in mind
- The wiki is aimed at all postmarketOS users, from novices to experienced users.
- The only base assumption is that the user is familiar with basic Linux shell commands like
ls
,cd
,cp
,mv
and similar. Besides this, do not make assumptions about the reader's abilities.
- The only base assumption is that the user is familiar with basic Linux shell commands like
- Avoid being too casual; do not use jokes, colloquial expressions or sarcasm.
- Do not use the documentation to express your own opinion (except under your user page).
- Avoid making cultural references, even in examples; the wiki targets a global audience, and the references may not be clear to all readers.
- Give correct, clear, tested examples. Do not add bad ("it's possible but you shouldn't do it") or non-working examples.
Page layout
- The page title should be in sentence-case, so only capitalize the first word (for example: "Mainlining guide" instead of
"Mainlining Guide"). - Start the page with a short paragraph describing the subject, or an introduction. Don't immediately start the article with a heading.
- Device pages and chipset pages are exempt from this rule.
- Use headings and subheadings to separate out relevant parts of a page.
- Do not use heading level 1 (
= text =
), start with level 2 (== text ==
). - Avoid heading level 4, and do not use levels 5 and below.
- If you're at nesting level 4 (
==== text ====
), re-consider how you split your higher-level sections.
- If you're at nesting level 4 (
- Don't skip levels when placing headings.
- Do not use heading level 1 (
- Avoid paragraphs longer than ~4 lines (assuming standard page width).
- At the same time, avoid making extremely short paragraphs (only a few words).
- Don't place newlines in the middle of sentences.
- Avoid sections longer than ~8 paragraphs.
- At the same time, avoid making extremely short sections (less than ~3 lines total assuming standard page width), especially if they use level 2 headings (
== text ==
).
- At the same time, avoid making extremely short sections (less than ~3 lines total assuming standard page width), especially if they use level 2 headings (
- Avoid duplicating page content. Link to another relevant page instead.
- Importantly, this means no full-page transclusions. It's confusing to see the introduction to another, clearly separate article, right after the intro to the current article.
- Some duplication is allowed for guide pages, where 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
- Use American English spelling (for example - "color" instead of
"colour"). - Avoid directly addressing the reader as "you". Try to use passive voice when possible.
- Guide pages (see #Guide pages section below) are exempt from this rule.
- Avoid redundant phrases such as "the command" or "the file/path/directory" (for example, "Use
pmbootstrap
to..." instead ofUse the").pmbootstrap
command to..." - In short enumeration lists, make the subject bold and place a dash ("-") separator between subject and description, for example:
- samsung-a5.img.xz - main rootfs image
- samsung-a5-boot.img.xz - Android boot partition
Wiki markup usage
- Always use internal links (
[[Page]]
) to link to wiki pages. Do not use external links ([https://wiki.postmarketos.org/wiki/Page]
).- Linking to sections is possible with internal links (
[[Page#Section name]]
), don't use an external link for this purpose.
- Linking to sections is possible with internal links (
- 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"
; prefix commands meant to be executed by a regular user with$
, and commands meant to be executed with root permissions with#
:$ whoami # Example user command user # whoami # Example root command root
- For single commands placed inline with the text (statements like "You can use
command
to do X"), the plain<code>
tag can be used.
- For single commands placed inline with the text (statements like "You can use
- When showing commands to run, use
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.
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 to emphasise a 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 formatting. A good rule of thumb is that for a specific section, you typically only want to make a couple of words bold in the first sentence of the first paragraph.
- Split the guide into separate sections - one section for each major step.
- 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.
- You can refer to the reader ("you" or "we") in guide pages.
Subpages
Splitting into subpages should be considered in the case when a single portion of a page takes up a significant (~40% or more) amount of the page's total length and/or contains subject matter not directly related to the main page's content.
A subpage should not be too short (under 4 paragraphs, or under ~20 lines assuming standard page width); too many subpages and the reader will be distracted or unable to find the information they're looking for.
If you split a long page into subpages, leave an introduction on the main page to ease the reader into the article and let them know where to start, then link to the subpages. (See how Installation does this.) Do not make a root page with nothing but links.