Help:Style: Difference between revisions

Latest revision as of 05:48, 17 March 2025

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.

Page title and headings

Page titles and all headings should use sentence case.
Avoid including Alpine Linux in headings.
Start headings at level 2, as first-level heading is used for page title.
Don't skip levels.

Page organization

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. A typical page with sections headings is given below as recommendation for all wiki pages:

    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.

Bulleted and numbered lists

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.

@@ Line 1: / Line 1: @@
-To achieve a consistent look and feel across all pages of Alpine Linux wiki, editors must follow the below style guidelines as much as possible.
+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.
 == Page title and headings ==
@@ Line 8: / Line 8: @@
 * Don't skip levels.
-== Section organization ==
+== Page organization ==
-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. The following sections hedings are recommended on wiki pages:
+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. A typical page with sections headings is given below as recommendation for all wiki pages:
 <Pre>
- === Prerequisite ===
+    Introductory section containing a concise summary of the page.
-  If there any Prerequisite, it must be properly listed here.
+ == Prerequisite ==
-  === Installation ===
+  If there are any Prerequisites, they must be listed here.
+  == Installation ==
    The Installation section must appear early in the page.
-  === Configuration ===
+  == Configuration ==
-   The Configuration section must follow with detailed sub-headings to handle all sub-topics.
+   The Configuration section must follow with detailed sub-headings to handle all subtopics.
-  === Troubleshooting ===
+  == Troubleshooting ==
    Troubleshooting section must include common errors that may be encountered by the users.
-  === See also ===
+  == See also ==
+  Add both internal wikilinks and external references relevant to this page in this section.
-   Add both internal wikilinks and external references relevant to the page in this section.
+   Add at least one category to which the page belongs to.
 </Pre>
@@ Line 52: / Line 56: @@
 Use [[Help:Editing#Transclusion|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]].
-Before making a new inclusion page, creating a regular page and linking to it instead. Including the same content in multiple page can be confusing for readers.
 == Category ==
@@ Line 60: / Line 62: @@
 == See also ==
 * [[How to write a HOWTO]]
 * [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style Wikipedia Manual of Style]