Help:Formatting for new pages
This page follows from the formatting essentials and demonstrates formatting templates that are useful (or required) when writing new pages.
Article description property
The [[Article description::]] property should be set on articles to provide a descriptive handle that can be automatically reused on other pages. Article descriptions are conventionally set in the lead-in sections of articles.
Article descriptions "capture" a section of text from an article to be used as the description property of that page, but in no way alter the rendering of pages. Select or write a section of text that properly describes the content or intention of an article, and surround it with the [[Article description:: and ]] tags.
The Article description property can be used in multiple ways across the wiki, for example the {{See also}} template leverages article descriptions to provide automatically-formatted, user-friendly, links in See also sections at the bottom of articles.
Here is a usage example:
| Source input | Rendered output in article | Use with {{See also|Firefox}} template |
|---|---|---|
Firefox is [[Article description::Mozilla's web browser.]]
|
Firefox is Mozilla's web browser. | Firefox — Mozilla's web browser. |
The full list of pages with the Article description property on the wiki can be found here. Take a look at the source of any of those pages for concrete examples of how to use this property.
Semantic MediaWiki is used by the Gentoo wiki to add support for annotating semantic data within wiki pages, and this extension provides the article description text property.
Article structure
This section describes how articles should be structured both in general, and for specific types of article which have their own particular structures (for example those describing a piece of software; or "meta articles" which describe a whole category of software).
Article blueprints aid with article creation by providing a predefined structure for pages of various types - articles should follow these structures to provide consistency across the wiki.
Titles and section headings
The title of an article should be short, specific and unambiguous.
Titles both of articles and of sections within an article ("section headings") should start with a capital letter, with the rest of the title using lower case (with the exception of proper nouns). This is called sentence case. Full capitalization (also known as "title case") should be avoided.
Section headings should be level 2 or higher (3, 4, ...). A level 2 heading uses two equals signs, i.e.: "== <title> ==".
The use of a level 1 heading is meant only for the title of the article itself, and is automatically used. As such, level 1 headings (i.e. "= <title> =") should not be defined in the article's text by wiki contributors.
Links and HTML formatting should not be used in section headings.
Start of an article
A wiki article should start with a short introductory paragraph, without any heading. The introductory paragraph should include a description of the article itself, and often these description sentences will be used as the Article description property.
Headings such as Introduction or Overview are highly discouraged: this information should usually just be included in the article header (the text at the top of an article, before the first section heading).
If an article requires any conceptual knowledge before the operational content of the article can be given (such as installation instructions, required configuration, package administration tasks, etc.) name these prerequisite sections according to the concept.
Documenting a package or software title
This section gives an overview of how to layout a specific type of article: articles for packages or software titles. For guidance on how to layout other common types of article, see the article blueprints.
When documenting a package or software title, add an {{InfoBox}} template to the beginning of the article, with external resources such as the project homepage, the category/package information (links to packages.gentoo.org), wikipedia article, ohloh statistics, etc.
Examples of what can be usefully added as InfoBox entries can be found in the software blueprint. Example of an InfoBox layout:
{{InfoBox stack
|{{InfoBox homepage|https://url/to/homepage|header=true}}
|{{InfoBox package|category/package}}
|{{InfoBox wikipedia|TitleOnTheWikipedia}}
|{{InfoBox ohloh}}
}}
Remember to use HTTPS whenever possible when adding external links to an InfoBox.
Following the blueprint: software articles should start with the "Installation" section with installation instructions, USE flag information and so on. A "Configuration" section will usually follow that can have info about configuration files, environment variables, and configuring the launch of daemons for different init systems, for example.
The central part of these articles will usually be one or more sections on the operational aspects of the software title or package. Try to structure this part on a use-case basis, with each subsection containing an entire operation. Examples of good sections could be "Manipulating the boot entries" or "Encrypting volumes with cryptsetup". It is good prictice to split sections up, so that their subsections each cover just one operation; "Manipulating the boot entries" could for example be split into "Listing boot entries" and "Adding a boot entry", etc.
Body
Adding new sections
The article body should include sections that are pertinent to the reader. For example, if an issue is frequently encountered when setting up a specific software package, then include a troubleshooting section about that issue.
Sections should be created on an as-needed basis, so new sections should not be added until there is content with which to fill them. Do not create empty sections expecting another contributor to provide the content (note that the {{Todo}} template may be used to show that required content has been identified for an article).
New sections (or even whole articles) can be drafted in userspace and moved to articles in the main namespace when finished.
End of an article
An article should finish up with links to related material: other Gentoo wiki articles, external websites, or references to source material (through <ref> tags in the article body). These sections are optional, but should be included if any useful resources are available.
Remember to add the "References" section when any <ref> tags are used in the article.
At the end of the article, add the following sections, as appropriate:
See also section
Add See also sections to reference other articles on the wiki that are related to the current article, contain further information about the current subject, or can be of interest to people reading the current page.
See also sections should consist of bullet lists of {{See also}} templates. Check that articles referenced using this template have the correct "Article description", so that the proper descriptive information will be shown in the list.
It can be helpful to add a short sentence to to inform the user how each element is related to the current article, or why it may be of interest.
External resources section
An external resource provides more information about the subject at hand than is available on the wiki. These sections are similar to See also lists, but link to pages outside the Gentoo wiki. These are often resources to help delve deeper into a topic, reference material, complete documentation, etc.
"External resources" sections should consist of bullet lists of URLs to external websites. It is useful to add a short description of each link, and as with "See also" sections it can be helpful to add a short sentence to to inform the user how each element is related to the current article, or why it may be of interest.