Help:Article naming guidelines
- Article naming is one of the most important tasks for wiki writers and editors.
- This article is a complete guideline on chosing article names, and also presents ArchWiki writers and editors with some issues to consider when naming their articles.
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.
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.
Titles like 'Boost Pacman' may be misleading for most readers. Some of the readers may be looking to boos 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. The example article may be renamed to read How to improve pacman download speed using wget, snarf, and lftp.
Allowing for article enhancement
In order to allow room for future edits and enhancements, a title 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, if you think you have covered all the bases. In the latter case, do make your article's name as specific as possible.
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
To make 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.
Using the long article name we have deviced 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
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.
To help readers understand what type of documents are available, ArchWiki has its pages sorted both by topic and by by type. If you look at the latter section, you will see all the possible article types that are available to wiki writers and editors.
Use the following table as a reference for article type siffixes:
|article type||suffix (in italics)||type 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||Q and A 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 taks.|
|Book||Article title book book||Container article for multiple related tutorials|
CAUTION: Article names have to be adapted to a suffix in most cases. If you decide to use a suffix, consider pephrasing your article's name to accomodate the suffix.
Remember that not only English-speaking users read ArchWiki. Articles are therefore required to have a language descriptor attached to the article's name. At the time of this writing, this is still not automated.
A language descriptor is attached by adding "_(Language)" to the article name (replace Language with appropriate language name). All articles should have the "_(Language)" language descriptor attached to their names.
NOTE: Currently, most ArchWiki articles are missing language descriptors because English language articles were considered base articles upon which translations are based. This is hopefully going to change, so the above guideline is still effective.
This guideline is effective as of its creation, but the correct procedures 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 left navigation panel to see if there were any changes.