Wikipedia:Manual of Style/Computing (failed proposal)

From Wikipedia, the free encyclopedia
Jump to navigation Jump to search

This page contains style guidelines for creating and editing articles on computers, software, networking, the internet and information technology. Other policies and guidelines should also be followed, and the general rules from the Manual of Style also apply.

Trademarks[edit]

Main page: Wikipedia:Manual of Style/Trademarks

For computer technology trademarks, adhere to Wikipedia policies and style guidelines regarding trademarks. For trademarks in all capital letters or all small letters, use an initial capital letter, as is standard with proper nouns in English. For example, Unix instead of UNIX. There is no reason to explain this in the body of each article.

Avoid common mistakes[edit]

Keep in mind what Wikipedia is not. Since it is not a dictionary, each term or product does not always get its own article. Often, they are combined into topics that can be the subject of a single high quality encyclopedia article.

Product directory[edit]

An article about a product should include a history of its development and major improvements. But, in the spirit of Wikipedia not being a directory nor indiscriminate, avoid a complete step-by-step record of every release or update. Common sense must be applied with regard to the level of detail to be included.

Avoid just pasting lists of features into the article, since they can become dated or removed as advertisement or copyright violations. Avoid relative time references (such as "currently", "lately" or "now").

Version versus product name[edit]

Each software product version must be referred to with the most common name.

Software vendors often use one of the following approaches to refer to a specific version of a software product:

  1. They include the version number in their reference, e.g. WinRAR 4, WinRAR version 3 and WinRAR v2.
  2. They change the product name with each release, e.g. Windows Vista and Windows 7.

Video games add a twist to this scheme. Video game vendors often make sequels and prequels for their most notable products. They use numbers in their video game titles to show their relationship. For instance Red Alert 2 and Red Alert 3 are two distinct but related video games. However, numbers that are part of the title are not version numbers. A separate version number may still be used. For instance, Red Alert 2 v1.008 is an updated version of Red Alert 2.

Consistently use the most common product name. For example, use Windows XP, not Windows v5.1 or Windows NT v5.1. Do not confuse and combine these methods, e.g. never use Red Alert v2 or Red Alert version 2 to refer to Red Alert 2. Do not invent novel short forms and abbreviations.

Service pack[edit]

Service packs or service releases are computer software that modify other computer software to fix their bugs or improve them. When referring to service packs, make proper distinction between the version of software product which is serviced via a service pack and the service pack itself.

To refer to a service pack, write down the full name of service pack. For example:

  • Windows XP Service Pack 2
  • WinZip 9 Service Release 1

To refer to a software product updated with a service pack, write: [Product name] with [Service pack name]. For example:

  • Windows XP with Service Pack 2
  • WinZip 9 with Service Release 1

Alternatively, where applicable, you can specify the version identifier of the software product for conciseness. For example:

  • Windows XP SP2
  • WinZip 9 SR-1

Try to use only one of these two styles consistently throughout the entire article prose. Using both may confuse the readers with little technical knowledge as they may not understand that both forms refer to the same entity. However, if both forms are frequently used in mainstream media (as was the case with Microsoft Windows service packs), the article must introduce both and establish their relation, before consistently using one.

x86 versus IA-32[edit]

Shortcuts

Exercise care while using the term "x86" because it can cause ambiguity. x86 is a type of CPU first developed by Intel, and later by others. There are two different variations of x86 in widespread use: IA-32 and x86-64. However, due to the dominance of IA-32, the term "x86" is often used to refer to IA-32 through metonymy. Therefore, these terms must be used with care.

Examples of use
Correct use Incorrect use Notes
"This computer program runs on IA-32 or x86-64." "This computer program runs on x86 or x86-64." Because x86-64 is one of the x86 variants, writing "x86 or x86-64" is at best redundant.
"This computer program runs on IA-32 but not x86-64." "This computer program runs on x86 but not x86-64." Because x86-64 is x86, "x86 but not x86-64" is self-contradictory.
"This computer program runs on x86, ARM and PowerPC" "This computer program runs on x86" x86, ARM and PowerPC are incompatible (mutually exclusive) CPU architectures, hence comparing them at cross-architecture (macroscopic) level is correct, even though the accuracy might not be sufficient in the more technical contexts. But, because "x86" alone is ambiguous, it must not be used without additional qualifiers.

32-bit and 64-bit[edit]

Do not use the terms "32-bit", "64-bit" or other such terms of bit lengths to refer to computer, CPU or software architectures. These terms are too vague and can cause a lot of ambiguity or misinformation.

These terms are often used to refer to two well-known CPU architecture types: IA-32 (a 32-bit variant of x86) and x64 (a 64-bit variant of x86). However, neither is IA-32 the only 32-bit CPU architecture, nor is x64 the only 64-bit CPU architecture.

Example of correct usage:

  • "This software application only runs on x64 CPUs."
  • "The IA-64 edition of this product [...]"
  • "The .z80 build created specifically for Zilog Z80 and compatible CPUs [...]"

Examples of incorrect usage:

  • "This software application only runs on 64-bit CPUs."
  • "The 32-bit edition of this product [...]"

Linux vs. GNU/Linux[edit]

Shortcut
See also: Talk:Linux/Archive 41 § Page move: GNU/Linux, and Talk:Linux/Referring to this article

Use "Linux" instead of "GNU/Linux" to refer to the family of operating systems based on the Linux kernel. The term "GNU/Linux" may still be written as part of the proper names of individual operating systems and Linux distributions.

The GNU/Linux naming controversy does exist, and "GNU/Linux" is a name advocated by the Free Software Foundation (FSF). Wikipedia, however, prefers the name that is most commonly used (as determined by its prevalence in reliable English-language sources). The consensus of discussions in Talk:Linux/Name is that the point of view of the FSF is not the common English-language usage.

Oft-neglected sources[edit]

Main pages: Wikipedia:Verifiability and Wikipedia:Identifying reliable sources

In Wikipedia, everything needs sources, including but not limited to software release dates, software package sizes, name and number of supported languages and the programming languages used to develop software products. Avoid any unreferenced assertions, including but not limited to "multilingual", "written in C++" or "developed for Windows".

Collocation[edit]

Avoid using strange forms of language. On the contrary, editors must stick to the most commonly used forms to make sure the readers feel at home. Do not use synonyms of a certain words just because they are synonyms; collocation is very important.

For instance:

  1. Computer programs that are no longer developed are called "abandonware". Do not use "forgottenware" or such novel terms. (See abandonware)
  2. The act of ceasing development of a software product is called "discontinuation". Do not use "abandonment" or similar alien terms. (See software release cycle and end-of-life (product))
  3. Computer programs run on a certain operating system or platform. Do not use "run under" or "run beneath".
  4. Computer programs run in context or within the context of a user account. Do not use "under", "beneath", "on", "inside" or "over". While these variations may be okay in informal speech, Wikipedia:Featured article criteria demands the use of professional style.
  5. "Log on", "Log in" and "Sign in" are all verbs that mean to "supply credentials for authentication". However, users either "log on to their computers" or "log in to their computers". They never "sign in to their computers". "Sign in" is only used for the authentication over the internet.[a] (See login)
  6. "Disc" and "disk" both refer to digital storage media. However, "disc" collocates with optical media as in Compact Disc and Blu-ray Disc, while "disk" collocates with magnetic media as in hard disk and floppy disk.

Tense[edit]

Shortcuts
See also: Wikipedia:Manual of Style § Verb tense

Always use present tense for verbs that describe genres, types and classes, even if the subject of the description (e.g. program, library, device) no longer exists, is discontinued or is unsupported/unmaintained.

The following example is incorrect:

  • TrueCrypt was a disk encryption program, released by TrueCrypt Foundation.

This sentence suggests that TrueCrypt is not a disk encryption program, although it once was. (Assume TrueCrypt has never changed its nature during its development lifecycle.) Grammatical deletion hides the fact that there are two "to be" verbs in this sentence; the more elusive fact, however, is that these two "to be" verbs are grammatically different: The first is a stative verb that does not change throughout its duration while the second is a dynamic verb which may cease to be valid after a duration when discontinuation occurs.

Use either of the following, whichever is more appropriate:

  • TrueCrypt is a discontinued disk encryption program. It was released by TrueCrypt Foundation.
  • TrueCrypt is a disk encryption program, released by TrueCrypt Foundation.

Optional styles[edit]

See also: MOS:STABILITY

The Arbitration Committee has ruled that editors should not change an article from one guideline-defined style to another without a substantial reason unrelated to mere choice of style. Revert-warring over optional styles is unacceptable.[b] Where there is disagreement over which of the styles to use in an article, maintain status quo.

Hence, avoid disputes over:

  • Choosing one of the many synonyms for a concept, e.g. "shareware", "trialware" or other synonyms; "x64" or "x86-64"; "proprietary software" or "closed-source"
  • Using one word or many words for the same concept, e.g. "x86" or "IA-32 and x64"
  • Ascending or descending sort order
  • Inserting one of the multiple URLs that all point to the same place and none has any advantage over the other
  • Any other multiple forms of the same thing

Screenshots of software[edit]

Main page: Wikipedia:Software screenshots

Command-line elements[edit]

Shortcuts

This section outlines the guideline for incorporating elements of terminals or command-line interpreters into Wikipedia articles, including syntax of shell commands or programs.

General guidelines[edit]

  • When providing command-line examples or discussing command-line elements, maintain clarity and simplicity.
  • Command-line elements should be presented in a monospaced font. For inline references, use <code>...</code> tag pair. In case of presenting multiple lines of command-line code, either prefix each line with a space character or enclose them all in a <pre>...</pre> tag pair.
  • Avoid referencing environment variables, dates, working directories, usernames, and hostnames unless they are relevant in the example.
  • Adhere to the following terminology:
  • When presenting arguments, maintain simplicity; specify them only when necessary and with clear explanations. Remember that Wikipedia is not a substitute for manual pages. Do not document the entire list of options associated with a command unless such descriptiveness has encyclopedic purpose.
  • Identify parameter placeholders with logical names in italics. These names should not contain spaces, as spaces are used to separate multiple arguments on the command line. The following are some examples:
    • (prompt) command parameter-name
    • (prompt) command ParameterName
    • (prompt) command parameter_name
    • (prompt) command parametername
  • Enclose optional arguments with square brackets: [ and ].
  • Specify repeating parameters using one of the following styles:
    • (prompt) command parameter0 [.. parameterN]
    • (prompt) command [parameter ...]
  • Zealously maintain consistency in applying optional styles explained above for the entire article.

Platform-specific guidelines[edit]

Microsoft Windows[edit]

The most common desktop operating system in use today is Microsoft Windows, whose command-line syntax has once been based on that of MS-DOS and OS/2; with the increasing popularity of Windows PowerShell, however, the style has moved towards that of Unix-like systems and programming languages. As such, stick to the DOS and OS/2 guidelines for command-line elements and examples of Command Prompt and Recovery Console. In case of the Windows PowerShell, however, adhere to the Unix-like systems and Windows PowerShell guidelines below.

CP/M, DOS and OS/2[edit]

The following additional guidelines are for command-line examples of the CP/M, DOS and OS/2 families of operating systems:

  • Write the names of internal or external commands, file and directory names (for as long as they fit into the 8.3 scheme) and environment variable names in all upper-case letters (such as DIR, AUTOEXEC.BAT or %PROMPT%).
  • While in principle DOS and OS/2 (and Windows) support both backslash (\) and forward slash (/) as a separator for directories, some programs (including most shells in their default configuration) support only the backslash. Therefore, use the backslash in examples of directory paths on local volumes unless it is important to indicate otherwise.
  • Various DOS systems support a user-configurable SwitChar (typically either a forward slash (/) or a hyphen-minus (-)), but not all programs adhere to it. Therefore, if the program supports it, use the default / in examples, unless it is important to indicate otherwise.
  • Standard options (of the form /C or -C, where C is some character) should also be upper-case, unless they are case-sensitive.
  • Contrast program names against built-in command names by appending their file extension. If a program is not included with certain versions (such as XCOPY.EXE or EDIT.COM), then the versions for which it is known to be included should be indicated.

Unix-like systems and Windows PowerShell[edit]

  • Shell builtin commands and cmdlets (such as cd and history) should be indicated as such.
  • Avoid shell-specific commands or utilities (such as the for loop or certain stream behaviors) whenever possible, because of the great variation in shells across Unix-like systems. If a shell-specific sequence is required for proper explanation, provide an example for the ALGOL-like shells (Bourne shell, Korn shell, and Bash) as well as one for the C-like syntax of C shell and tcsh.
  • Adhere to case-sensitivity requirements of the shell. The names of most commands on Unix-like systems are entirely in lower-case characters while the shell and operating environment are both case-sensitive. Windows PowerShell is not case-sensitive; so write cmdlet names in their natural English form to ease reading and memorizing. Write Unix-derived aliases (such as ls and cp) in lowercase. Use the Lowercase title or Wrongtitle template when necessary.
  • Differentiate commands that normally require privileged access from those that do not require it.
  • In some cases, the value of a parameter will commonly contain shell metacharacters. In these cases, it may be wise to specify quoting in the example to prevent users from receiving errors that to them will seem strange and unrelated.
  • Always specify the minimum (and, if applicable, the maximum) version number of the shell that supports the command. Linux (owing to its open-source nature) and Windows PowerShell may introduce new commands at any time.

Providing sample output[edit]

It may often be useful to provide a sample of the output that a command generates. In these cases, the full command and all arguments as they were typed are given. The output of the command will therefore be specific to environment and other variables. The tags <pre>...</pre>, <nowiki>...</nowiki> and <SyntaxHighlight>...</SyntaxHighlight> (with proper arguments) prevent conflicts with the wiki markup syntax.

Examples of usage[edit]

DOS examples[edit]

The DIR built-in command on DOS, which lists files and directories: 

> DIR [options] [pattern ...]

The program MOVE.EXE on MS-DOS, whose behavior had to be emulated prior to its introduction: 

> MOVE.EXE source target

Unix examples[edit]

The ls command on Unix-like systems, which lists files and directories: 

$ ls [options] [file ...]

The mkfs command, which creates new file systems. It usually requires privileged access, so the prompt character is # instead of $ 

# mkfs [-t fstype] [fs-options] device

The wget program, one of the GNU utilities, which retrieves files given a Uniform Resource Identifier (URI). URIs can sometimes contain shell meta-characters, and so the parameter is usually quoted to prevent errors. 

$ wget [options] "URI"

The if built-in structure, whose syntax varies. In Bourne shell, Korn shell and Bash: 

$ if command ; then command ; ... ; fi

In C shell and tcsh: 

% if (expression) then command ; ... ; endif

Sample output of the df command, which lists disk space usage on mounted file systems: 

$ df -P  Filesystem          512-blocks      Used Available Capacity Mounted on  /dev/hda2             39331760   7398904  29834768      20% /

License[edit]

Try to specify the licensing terms of the subject of a computer program article accurately and concisely.

License agreements usually specify one or more of the following:

  1. Environment of use (e.g. commercial, non-commercial, personal, educational, non-military, etc.)
  2. Cost of use (e.g. free of charge, one-time payment, subscription-based, etc.)
  3. Applicable licensees (e.g. unrestricted, one computer, one user account of a computer, one user, volume licensing, etc.)
  4. Other rights (e.g. the right to study, modify, reverse-engineer, etc.) or restrictions (e.g. of use for producing pornographic contents)

Wikipedia has articles about the most common software licensing schemes. Therefore, most of the times, one or two wikilinked words in the infobox can describe the licensing scheme. For instance GPL, Freemium, BSD license or Proprietary commercial software (Write: [[Proprietary software|Proprietary]] [[commercial software]]). Avoid vague or outright non-informative phrases like "Vendor's EULA", "Multiple" and "Unknown".

Website addresses[edit]

Shortcut
See also: Wikipedia:Manual of Style/Linking

Exposed URLs[edit]

Certain areas of Wikipedia such as infoboxes require website addresses (URL) to be exposed in print. To maintain readability and conciseness, certain parts of the web addresses may need to be hidden or their shorter forms used.

A web address consists of several parts, with the following examples showing some of the most commonly seen ones:

Scheme Fully qualified domain name (FQDN) Request
http:// www.wikimedia.org /
http:// windows.microsoft.com /en-US/internet-explorer/products/ie/home
https:// commons.wikimedia.org /wiki/Main_Page

However, the reader does not need to see all of these somewhat unappealing and hard-to-remember items, thanks to the web browsers and web servers' ability to infer them. Often, the following parts can be omitted:

  1. Scheme: Omit http:// in the displayed URL but not in the underlying link; the {{URL}} template hides this scheme automatically. Other schemes like https:// and ftp:// need to stay.
  2. Request: When the request part is only a single slash character (/), omit it; the {{URL}} template hides this automatically. Users often omit the single slash character as the only request specification and expect the URL to work properly.

The omission is only sanctioned when the functionality is undeterred. Always test the resulting URL. In the rare cases that www. or / are required, it is recommended to leave an invisible wiki-markup comment to notify future editors.

If the target website provider has provided shorter alternative URLs to the webpage, use them. The only exception to this instance are short URLs that use hard-to-remember numbers. For instance:

When the following are valid... ...avoid the following
microsoft.com/ie windows.microsoft.com/en-US/internet-explorer/products/ie/home
https://commons.wikimedia.org/ https://commons.wikimedia.org/wiki/Main_Page
beautyoftheweb.com go.microsoft.com/fwlink/?LinkId=214371

Do not use URL shortening services such as bit.ly. Such URLs are maintained by independent entities and are susceptible to link rot. (See also: URL shortening § Shortcomings)

Choosing between HTTP and HTTPS[edit]

In the event that the linked website serves contents over both HTTP and HTTPS protocols, i.e. it accepts URLs with both http:// and https:// schemes, observe the following:[c]

  • Use https:// scheme for sites that only serve contents over HTTPS, or which support both HTTPS and HTTP. This also includes websites that do accept http:// addresses but redirect them to https://.
  • Use http:// scheme for sites that do not support HTTPS at all.
  • Wikipedia formerly used protocol relative links for sites that support both HTTP and HTTPS (for example: //example.com/ instead of either https://example.com/ or http://example.com/). However, as Wikipedia itself now requires HTTPS, this is now deprecated.

See also[edit]

Notes[edit]

  1. ^ For the first time, Windows 8 has used "sign in" instead of "log in" but as of October 2012, this exception has remained a negligible minority.
  2. ^ See Wikipedia:Requests for arbitration/Jguk § Principles, Wikipedia:Requests for arbitration/jguk 2 § Principles and Wikipedia:Requests for arbitration/Sortan § Principles
  3. ^ The original discussion can be found in Wikipedia:Village pump (policy)/Archive 111 § As WP uses HTTPS, should (some) external links, too?
Retrieved from "https://en.wikipedia.org/w/index.php?title=Wikipedia:Manual_of_Style/Computing_(failed_proposal)&oldid=1095394164#Command-line_examples"