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

For consistency across the wiki, article pages follow certain layout and organization guidelines. See sample page layout for a complete example.

A wiki page needs the following mandatory elements:

• Page title
• Introduction section
• Section headings
• Category

The following are optional elements:

• Magic words
• Metadata
• See also section

Mandatory elements

Page title

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

"Introduction" section

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

Use standard headings like Prerequisite, Installation, Configuration and Troubleshooting to organize information as shown in sample page.

Follow the formatting guidelines given in Page title for section headings too. Start headings at level 2, as first-level heading is implicitly used for page title. Don't skip levels.

Category

Every article page should have at least one category from among the categories list. They must be placed at the bottom of the page.

Optional elements

Magic words

The optional Magic words, if used, should be placed as the first entry in the wiki page. They can be used to alter how an article title, Table of Contents(TOC) are displayed.

Metadata

Metadata like version or status tags help users to quickly see the relevance of the page.

Status tags like Template:Verified, Template:Obsolete or Template:Accuracy can be added at the page or section level, especially when writing new articles or updating existing ones.

Version information can be added using Template:Pill to provide visual clarity or Template:Pill_clickable for linking to release notes or references. These can be used at page level or section level or even at a specific line of a wiki page, depending on their relevance.

"See also" section

Use See also section for placing both internal wikilinks and external links that are relevant to the page.

Content guidelines

General principles

When adding or editing content, place it in the most appropriate page or section and add reference from other pages. New pages must be created sparingly, i.e., only if it is absolutely needed. Updating existing wiki pages benefits existing wikilinks.

Pay proper attention to name new pages as changing the name of pages in the wiki is not trivial. Adding or editing section headings must be done with care, as they can be linked within the page and from other wiki pages.

Refer to existing wiki pages for standard tasks like installation, partitioning, formatting, user management, managing repositories etc. This avoids confusing users and prevents content fragmentation.

Code and commands

To ensure clarity, standardized visual style, and proper handling of characters, editors should make use of Alpine Linux wiki specific templates listed in Help:Cheatsheet. HTML elements should be used sparingly.

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.

• 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

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

External links should not normally be used in the body of an article and instead place them in "See also" section in addition to internal wikilinks. Exercise care when adding external links. Do not use the wiki for self-promotion.

Check links and ensure that the destination is the intended one.

Transcluded pages

Use transclusion for content needed in multiple pages. To quickly identify such pages, add Include: in front of the regular title (e.g., Include:Setup-desktop).

Use transclusion sparingly, as inappropriate placement can break pages or confuse readers. If possible, consider using a regular page and linking to it instead.

User pages

User pages are subpages in the User namespace like User:Username/. These pages are meant to keep personal notes, references or for drafting and the above instructions are not applicable for them. Do not add a category or redirect links to User pages from Main namespace. Note that user pages are not part of default search.