sasCommunity:Titles

From sasCommunity
Jump to: navigation, search
This page is a sasCommunity work in progress. Please feel free to contribute your thoughts, too.

Whenever you create an article you need to give it a Title. The title is the name that identifies your article to the wiki and the world. In this article you will find some best practice advice on how to give your article a title. It aims to explain what works well, what doesn't and why.

How titles are used

To appreciate the advice that follows you first need to understand how the title of an article is used to refer to the article concerned.

  • The title you use for your article will be converted to a wiki URL, with underscores replacing spaces and the first letter capitalised.
  • To refer to your article in another article, you can enclose the article title inside double square brackets ([[ ]]) to create a wiki link. The text inside the square brackets is then converted to a wiki URL by capitalising the first letter and replacing spaces with underscores. If a matching article title already exists on the wiki then the word(s) enclosed by the square brackets appear as a blue wiki link, otherwise the title appears as a red wiki link and is listed as a wanted page.
    • A good way to start a new article is to edit an existing article and enclose the words that form a proposed title in double square brackets. When you save your edit to the existing article, the words of your proposed title should then appear as a red link, (or a blue link if that title is already used). To start creating your article, simply follow the red link. Creating a new article this way stops your article being considered an orphaned page.

Capitalisation

In general, the capitalisation of an article title should be the same as you would write it in ordinary text. Usually this means writing the title in lower case. The first letter of the title is automatically capitalised by the wiki, but the rest of the title should be in lower case unless there are very good reasons use upper case.

Here are a few exceptions that prove this rule.

Note: Incomplete list. (Feel free to add to this list.)

SAS keywords

SAS keywords should be written in UPPER CASE. This is a typographical convention used by numerous authors of SAS books.

Proper Names

Use proper capitalisation for proper names. This usually means capitalising the first letter of each word. Brand names should be capitalised appropriately, too.

Bibliographical references

If your article is essentially a bibliographical reference to, or abstract of, a book, presentation, paper or other document, then the capitalisation should follow that used by the document you are refering to. To minimise confusion, you should use the exact title used by the document concerned, capitalised in the same way.

For brevity, you should omit references to the author, conference, paper number, publisher, or year of publication. You can also omit any byline or subtitle that follows the main title, provided there is no confusion with a different document that has the same title. Avoid including a reference to the type of document (i.e. book, paper, presentation, code, etc.) or format (PDF, TXT, SAS, etc.) in the title of the article, since your article should cover who wrote and published the document(s) as tell as the contents of all the alternative formats and all the associated resources. (Note: If you are uploading files, the file name does not follow these rules and the file format should be indicated by its extension.)

Punctuation

Be very careful when using punctuation symbols in article titles. Some punctuation symbols have special meanings for the wiki, and you may discover your article title does not work correctly. Although an article title will usually display the punctuation symbols you use, the underlying wiki URL will be different.

Avoid these symbols, if you can:

Underscore symbol (_) 
The underscore symbol (_) is used to replace spaces in wiki URL's for titles. If your title contains an underscore, it will be converted to a space in the title used and displayed by the wiki.
Colon (:) 
The colon symbol (:) is used by the wiki to identify namespaces. All the text before the colon identifies a namespace. If the colon is the first character in a title the article may not be accessable.
Slash (/) 
The slash symbol (/) is used by the wiki to identify sub-pages. If another article has the title of the text that appears before the slash then your article will be treated as a sub-page of that article. More generally, the slash used in internet URL's and file systems to identify sub-directories and the end of a URL.
Question mark (?) 
The question mark symbol (?) is used by the internet as an escape character to identify URL parameters. When a wiki page is actioned (edited, etc.) the question mark symbol is used to identify what page is being actioned and what action is to be performed. If your title is a question, consider rephasing it as a statement.
Period (.) 
The period symbol, (or full stop or dot) (.) is used as an escape character for unicode and other symbols that cannot be used in internet URL's. It is also used to identify a file extension in a URL.
Percent symbol (%) 
The percent symbol (%) is used as an escape character for unicode and other symbols that cannot be used in internet URL's.
Pound or Hash symbol (#) 
The pound or hash symbol (#) is used in a URL to identify a page anchor, or bookmark, associated with the headings of a page. The wiki will usually not create articles with this symbol because any wiki links that use this symbol are referring to the section of the page named before the symbol that has a heading that appears after the symbol.
Pipe or Vertical Bar symbol (|) 
The pipe or vertical bar symbol (|) is used to create wiki links with words that are different from the article title.
Parentheses ( and ) 
Parentheses ( and ) are used when disambiguating ambiguous titles. If used to enclose text at the end of a title, wiki links can be created to refer to the page without using the words enclosed in the parentheses and without needing to rename the wiki link. By convention, an article having a title before the enclosed text is presumed to be a disambiguation page. If you are using parentheses because your article has, or needs two different titles, consider using redirection pages instead of enclosing one of the titles in parentheses.
Square Brackets ([) and (]) 
Single square brackets ([) and (]) are used to form web links to external URL's. Double square brackets ([[) and (]]) are used to form wiki links to wiki articles. The wiki will usually not create articles with square brackets because they cannot be referred to via wiki links.

Wording

Because titles are used to form wiki links, they should use words and phrases as they would commonly be used in written text. Here are some things to consider.

Singular or plural

Use a singular word rather than a plural word if your title could be wiki linked either way. If it is easier to turn a singular term into a pural term by adding an "s" then a singular word will probably make a better title.

Articles - The and A

Avoid using either a definite (The) or indefinite (A) article to start your title, unless that is the way it will always be referred to.

Meaning

The title of an article should describe the subject, topic or contents of the article in clear and unambiguous terms. When somebody reads the title of an article, they should be able to tell, in general terms, what the article is likely to be about.

Avoid giving your article a misleading or ambiguous title as you are likely to find your article will be edited mercilessly to conform to its title, or else moved to a different title that more accurately describes its content.

Be Specific

Be specific about the subject of your article. The title should concisely describe the content in reasonably specific terms.

If you are writing about something with a particular name then use that name as the title. For example, if you are writing about a paper or presentation use the title of the paper or presentation.

Generic terms

A generic title implies a generic article. Only use a generic term if you want the article to be a high level overview or to (eventually) deal with the total subject area. Consider what a title means if it is enountered in a different context or in isolation, without knowing it came from the sasCommunity.org wiki. Does this change what you would expect to read when you followed the link?

What sort of articles do you expect for 2010, 2011, big data, delete, etiquette, Software Engineering, style sheet, Structured Query Language, for example? Do these articles meet the expectations that their titles give you? Do you feel like contributing what you know to any of them? Do you want to (re)write any of them from scratch? What would you say about the title?

Uniqueness

The wording of your title should be unique, to avoid confusion with other articles. No two articles can share the same title.

Also articles about the same topic are likely to be merged, especially if they have similar titles. If somebody else has already started writing about the topic you are wanting to write about, consider contributing to their article, rather than creating a new article under a similar name. If your article duplicates the meaning of another article, even though the wording is different, you are likely to find both articles will be edited mercilessly to eliminate the duplication and end up being merged together.

Specific subject areas

If you are creating articles in one of the following subject areas, here are some more things to consider.

Employment opportunities

Employment opportunities should include the job title as well as the city, state or country the opportunity is in. Including the name of the employer, or field of work, may also be helpful in attracting the right candidates. Be concise with your title. Ask yourself: If the ideal candidate for this opportunity saw that title, would they read the article?

When capitalising job titles, just capitalise the first letter of each word in the title. Please avoid writing the whole article title in capital letters as this clashes with the style of other employment opportunity listings. Abbreviations that are normally capitalised, such as trademarks like SAS, or state and country abbreviations should remain capitalised. Separate the job title, company name, city, state and country with commas.

Publications

If your article is about a publication, especially if it will be an abstract or review of a book, paper or presentation, then the title of the article should be the same as the title of the publication. The reason for this is that it is easier to be certain that your article is talking about the publication concerned, if, for any reason, the publication goes out of production or can no longer be found where you said you found it. This often happens with books, papers and presentations hosted on a third party's website. What you found today, may not be there tomorrow. Publications go out of print, or are superseded by a new edition or a different title. Websites are reorganised, or go off-line. People die and businesses cease to exist, or the bills are left unpaid. As a result the resources for that publication disappear and the only thing left is your wiki article.

Sasopedia

Sasopedia articles about SAS code should follow the conventions already used by authors of other articles about SAS code. SAS keywords should be capitalised. When writing about a specific keyword used in a particular context, mention the keyword first followed by the context concerned. Examples include:

SYMGET Function
PRINTTO Procedure

Avoid writing SAS code fragments. A title like THE context should be used rather than CONTEXT THE or Context the, because your article is about the THE keyword found in a particular context, not the CONTEXT keyword as it applies when it precedes the THE keyword when written in SAS code.