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 5: / Line 5: @@
 * Page titles and all headings should use [https://en.wikipedia.org/wiki/Letter_case#Sentence_case sentence case].
 * Avoid including '''Alpine Linux''' in headings.
-* Start headings at level 2, and don't skip levels.
+* Start headings at level 2, as first-level heading is used for page title.
-* First-level headings and their formatting is used for article title.
+* Don't skip levels.
-== Standard sections ==
+== Page organization ==
-The following sections are recommended on all 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:
- === Prerequisite ===
+<Pre>
+    Introductory section containing a concise summary of the page.
-  If there any Prerequisite, it must be properly listed here.
+  == Prerequisite ==
- === "Installation" section ===
+  If there are any Prerequisites, they must be listed here.
-  The Installation section must appear early in the page.
+  == Installation ==
- === "Configuration" section ===
+  The Installation section must appear early in the page.
-  The Configuration section must follow with detailed sub-headings to handle all sub-topics.
+  == Configuration ==
- === "Troubleshooting" section
+  The Configuration section must follow with detailed sub-headings to handle all subtopics.
-  Troubleshooting section must include common errors that may be encountered by the users.
+  == Troubleshooting ==
- === "See also" section ===
+  Troubleshooting section must include common errors that may be encountered by the users.
-  Add both internal wiki links and external references relevant to the page in this section.
+  == See also ==
-== Page category ==
+  Add both internal wikilinks and external references relevant to this page in this section.
-Every page should be assigned at least [[Help:Editing#categories| one category]] from among the list of [[Special:Categories|categories]].
+  Add at least one category to which the page belongs to.
+</Pre>
+== 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 [[Help:Editing#Links|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 [[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]].
+== Category ==
+Every page should be assigned at least one [[Help:Editing#categories|category]] from among the [[Special:Categories|categories list]] by placing them at the bottom of the page.
 == See also ==
-[[How to write a HOWTO]]
+* [[How to write a HOWTO]]
+* [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style Wikipedia Manual of Style]
+* [https://wiki.archlinux.org/title/Help:Style Archwiki Help:Style]
 [[Category:Wiki]]