LanguageUsageGuide

This document provides guidance on language usage in Foswiki product documentation.

For a mapping of older terms to new ones introduced by the Foswiki project, see the TWikiTerminologyMap page.

For guidelines on writing, see HowToWriteBetterCopy.

Foswiki terminology

• WikiWord and WikiName should be used in their linking form and not spaced out.
• When used frequently, it is recommended to escape the subsequent duplicate instances, or disable autolink and explicitly link the first occurrence rather than spacing out the terms. This allows for easier and more consistent translation.

Automatic Linking

• The System web should be functional even if NOAUTOLINK is enabled. Important links should always be written in explicit link format [[LinkingTopic]].
• If there is any expectation of the topic being included from other webs, write them in the format of [[System.WikiName]], as WikiWords link in the context of the base web and will be broken links when included in other webs.

Email

Preferred spelling.

Factoring

See " Reorganizing/rewriting".

Foswiki

"Foswiki" (leading uppercase F, trailing lower case letters) is the name of the project and its primary product. Use it when referring to the project itself or the specific product as distributed by the Foswiki project. Take care to not use Foswiki in a way that may lead to confusion with any other products, projects, services, or organizations.

The WIKITOOLNAME macro is used to store the name of a specific Foswiki installation. It is set in System.DefaultPreferences and allows a specific site deployment to be branded for the needs of the client. Use %WIKITOOLNAME% in documentation intended for to help users of a specific installation; that is, for those who write text and store information in the site, and who maintain Wiki applications. Use "Foswiki" in documentation intended for admins who are maintaining the installation itself, where the project or the product is being referred to.

Nouns preceded by adjectives

Please note that in English, no hyphen is required between an adjective and a following noun. For example, use "Foswiki release" or "Foswiki contributor".

Reorganizing/rewriting

Invitations to users to reorganize and rewrite text should use the terms "reorganize" and "rewrite". "Factor" as a verb has a mathematical meaning, and "refactor"/"factor" is jargon in software development, but "factor" is not in wide mainstream usage. In the context of writing, "factor" does not add any additional semantic value over "reorganize" or "rewrite".

TWiki

The term TWiki can be used when referring to the TWiki product or project, or to a software API that uses the TWiki symbol. Care must be taken that the term TWiki is not used to refer to the Foswiki product or project, nor in any way that can lead people to confuse Foswiki with TWiki.

%WIKITOOLNAME%

See " Foswiki".