Article naming guideline (English)

From ArchWiki

Jump to: navigation, search
Article summary
This article discusses effective article naming strategies and considerations to ensure readability and improve navigation of the wiki.
Available in languages
English
简体中文
Related articles
ArchWiki Tutorial (English)
Short article names HOWTO (English)

Article naming is one of the most important tasks for wiki writers and editors. This article is a complete guideline on choosing appropriate article names, and also presents ArchWiki writers and editors with some issues to consider when naming their articles.

Contents

About article names

Article names serve two purposes. They are identifiers of the wiki content on the ArchWiki site. Also, they are means by which readers identify the content. Therefore, an article name has to be unique and descriptive.

Sometimes, article names reflect the type of article content, and also offer additional information like language in which the article was written.

Descriptive names

Names should be as specific as possible, and they should reflect the article scope.

Documentation projects are seldom like software/hardware reviews commonly seen in newspapers and news sites. Documentation is usually read when some problem arises, or some other specific need has to be met. Therefore, quick identification of those needs and swift solution is of utmost importance. For improved readability and faster access to information, article names (and, therefore, their titles) should be as descriptive and specific as the article scope permits.

Example

Titles like 'Boost Pacman' may be misleading for most readers. Some of the readers may be looking to boost some aspect of pacman, and that aspect may not necessarily be the aspect described in the article. Therefore, the article name must be as specific as possible without being too long to quickly scan. Such an article may be renamed to read How to improve pacman download speed using wget, snarf, and lftp.

Allowing for article enhancement

Names should be general enough to allow for future enhancement of the article contents.

In order to allow room for future edits and enhancements, an article's name sometimes needs to be less specific. Of course, making article names less specific just for the sake of shortening it is not a good idea. On the other hand, if you think you have covered all the bases, and that no future edits will enhance the article's scope, make your article's name as specific as possible.

Example

Let us go back to the previous example. The new title of the article is Improve pacman download speed using wget, snarf, and lftp. However, some day, new download mangers may emerge that would replace or become an alternative to wget, snarf, and/or lftp. This calls for a more generic title, something like: How to improve pacman download speed using alternative download managers.

Shorten article names

Names should be as short as possible.

Making article names short is important in order to allow quick scanning of article listings. Many people use the browsing technique when reading wikis, so you don't want to waste their time by writing article names that are miles long. Also, shorter names tend to sound more professional.

Example

Using the long article name we have devised in the previous examples (How to improve pacman download speed using alternative download managers), we will demonstrate how to shorten the title in a separate article.

Article type suffix (recommendation)

Names shoud have a type suffix.

Note: This is a recommendation, and not a rule. You are expected to consider, but not necessarily apply the rule.

Although the type of the article is not critical, it is more than helpful when readers are trying to find a quick (rather than complete) solution to a problem. For instance, HOWTOs are considered a short, step-by-step guide for a simple task, whereas tutorials are considered a much more complete guides on how to carry out many related tasks.

Use the following table as a reference for article type siffixes:

Article type Suffix (in italics) Description
HOWTO Article title HOWTO Short, step-by-step procedures for carrying out a single task
Tutorial Article title tutorial Longer, comprehensive guides to carrying out a set of related tasks
FAQ Article title FAQ Question-and-answer type of articles of varying length
General (no suffix) General articles that do not cover any specific task, procedure, or guidelines
Guideline Article title guideline Standards for community behavior or carrying out a task or a set of tasks.
Book Article title book book Container article for multiple related tutorials
Warning: Article names have to be adapted to a suffix in most cases. If you decide to use a suffix, consider paraphrasing your article's name to accommodate the suffix.

Multi-language articles

Names are required to have a language identifiers.

Remember that not only English-speaking users read ArchWiki. Articles are therefore required to have a language identifier attached to the article's name. At the time of this writing, this is still not automated.

A language identifier is attached by manually appending "_(Language)" to the article's name (replace Language with appropriate language name). All articles should have the "_(Language)" language identifiers attached to their names.

Note: Currently, most of the ArchWiki articles are missing language identifiers because English language articles were considered base articles which were then translated to other languages. This is hopefully going to change, so the above guideline is still effective.

Example

For example, if you have an article called Pacman (English), you would call the Japanese translation Pacman (日本語), and the Serbian translation Pacman (српски).

Notes

This guideline is a working version, but the procedures outlined here may still be changed at any time. You may want to mark this page as watched by clicking on the "Watch this page" link at the bottom of this page, and also visit the "My watchlist" in the navigation panel to see if there were any changes.

Personal tools