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. Refer to sample page based on this page.

Page layout and organization

A wiki page needs the following elements:

Page title
Magic words(optional)
Table of contents (automatically generated)
Status tags(recommended)
Introduction
Article specific headings
See also
Category

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. Commonly used magic word is {{DISPLAYTITLE:title}}, to alter how an article title is displayed, like in dwm page.

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 section headings too.
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.

Metadata

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

Version and status tags

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. 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.

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.