Help:Style

To achieve a consistent look and feel across all pages of Alpine Linux wiki, editors are requested to follow the below style guidelines as much as possible. This page only deals with the common conventions to be followed, as there are specific pages like Help:Editing and Help:Cheatsheet for the technical aspects.

Page layout and organization

Page title

Page titles should use sentence case.
Avoid including Alpine Linux as it is mostly redundant in this wiki.

Magic words

Magic words are optional. If used, they should go at the very beginning of articles. Best known and commonly used magic word is {{DISPLAYTITLE:title}} - this alters how an article title is displayed. Refer to dwm page for an example.

Introduction

Every page should begin with an introductory lead section – a concise summary of the article – which is never divided into sections. The remainder of the article is typically divided into sections.

Section headings

Follow the guidelines given in Page title for all section headings.
Start headings at level 2, as first-level heading is used for page title.
Don't skip levels.
Currently numbered headings are not enabled in Alpine wiki. Since the current css doesn't clearly differentiate between heading levels like H3,H4,H5 etc..i.e beyond H2, do not create too many levels and instead use H2 level if needed for clarity.

Sample page layout

A typical sample page with sections headings is given below as recommendation for all wiki pages including Howto's:

Introductory section containing a concise summary of the page.

== Prerequisite ==

If there are any Prerequisites, they must be listed here.

== Installation ==

The Installation section must appear early in the page.

== Configuration ==

The Configuration section must follow with detailed sub-headings to handle all subtopics.

== Troubleshooting ==

Troubleshooting section must include common errors that may be encountered by the users.

== See also ==

Add both internal wikilinks and external references relevant to this page in this section.

Add at least one category to which the page belongs to.

Metadata

The following elements ensure that the content is easily usable and maintainable.

Version tagging

Editors are strongly encouraged to include version or status tags like Template:Verified, Template:Obsolete or Template:Accuracy at the page or section level, especially when writing new articles or updating existing ones. These helps users to quickly see the relevance of the page.

Use Template:Pill to provide visual clarity
Use Template:Pill_clickable for linking to release notes or references

These templates can be used at page level or section level or even at a specific line of a wiki page, depending on their relevance.

Content fragmentation

To avoid content fragmentation and for easier maintenance of wiki, it is important to follow the guideline Do Not Repeat Yourself in Wiki. At all times, place the content in the most appropriate page or section and add reference from other pages.

Formatting guidelines for code and commands

To ensure clarity, standardized visual style, and proper handling of characters, editors must use the available templates like Template:Cmd, Template:Cat etc for all technical elements. Using html elements like <Pre> should be used sparingly. The Templates subsection of Help:Cheatsheet documents most commonly used options.

Tables and lists

Tables are effective in presenting a summary or overview or when listing rows of information. Avoid using a table and instead use lists if there are only few rows as table markup often complicates page editing.

Lists can be either bulleted or numbered. Understand how to use lists or check the Cheatsheet.

Do not use lists if a passage is read easily as plain paragraphs.
Use numbers rather than bullets only if:
- a need to refer to the elements by number may arise;
- the sequence of the items is critical;

Links

Make links only where they are relevant and helpful in the context: Excessive use of hyperlinks can be distracting and may slow the reader down. Add links only that are worth pursuing.

Check links: Ensure the destination is the intended one and test them.

External links should not normally be used in the body of an article and instead Use #See also section for placing them. Add external links with discretion and do not use wiki for self-promotion.

Transclusion

Use transclusion for content that may be required in multiple pages. To quickly identify such pages, title such pages with Include: in front of the regular title. For eg: Include:Setup-desktop. Add adequate notice to editors using the standard html comment syntax..

Using Transclusion must be restorted sparingly as they can easily break pages and viewing the same content in multiple page can be confusing for readers. So consider creating a regular page and linking to it instead of using Transclusion.

User pages

All the above instructions are not applicable for User pages i.e User page and subpages in the User namespace like User:Username/. These pages are meant to keep personal notes, references or for drafting.

Do not add category to User pages.
Do not add redirect links to User pages from Main namespace.
Note that user pages are not part of default wiki search.
Do not use article-specific templates like Template:Draft, Template:Obsolete, or Template:Todo etc on your user pages unless you are testing the templates itself.