Article naming guideline (English)
From ArchWiki
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.
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 |
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.
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.