Vim Tips Wiki:Title guidelines

Vim Tip Guidelines
Quick reference
General guidelines
Titles and renaming a tip
Comments
Categories
Discussion page
Merging similar tips
Deleting a tip
Templates
Formatting code blocks
Entities and other magic
Script comments

In short

The URL referring to a tip should be short, simple and meaningful. That will help if you need to post a link to a tip in a web page or mailing list.

To achieve a short, simple and meaningful URL, the title for a tip:

• Should be short.
• Should avoid punctuation.
• Should use words referring to the problem solved by the tip.

There is no need for a title to use extreme precision. If someone is interested in tips on searching, they will look at any tip with "search" in the title. The title does not need to precisely describe the search method.

Apart from making an ugly URL, there are lots of characters that cause trouble in a title.

These characters are not possible due to technical restrictions:

# < > [ ] | { }

These characters are possible, but should be avoided in almost all cases:

/ ? + _ : %

We try to avoid these characters, but they can be used in some circumstances. In particular, a tip that needs to refer to the C++ programming language can use "C++" in the title (however, bear in mind that the URL will use "C%2B%2B"). Note that you cannot use "C#" in a title.

The slash and colon characters can sometimes be used, but they also have special meaning to the MediaWiki software (a slash is used for subpages, and a colon is used for namespaces). Please try hard to avoid them.

Suggestions for good titles

• Try to remove all punctuation.
• Remove "How to" and other noise words.
• Remove references to Vim (we assume tips are about Vim).
• If keeping the name, spell it as 'Vim' (but use 'gvim' – sorry about the inconsistency).
• Remove "best", "good" etc (judge tip on its merits, not title).
• Try to maintain consistent tense ("Change ..." rather than "Changing...").
• All words are lowercase, except that the first word and proper names are Capitalized.
• Use "Windows" (not "windows") if referring to Win32 (and never "Windoze", "Winblows", etc.).
• Try to identify the point of the tip.
• Some titles refer to what we hope the tip will become, rather than what is currently achieved.
• Remove version numbers from titles (we hope the tip will be updated to work with the current version of whatever utility the tip refers to).

Unless you're sure you have a good title, perhaps you could add a comment saying that you think the tip should be renamed to "Your suggestion here". Add that to the "Comments" section at the bottom of the tip (not on the talk page). Leaving a comment gives other people the opportunity to make suggestions so we avoid the confusion of renaming a tip, then later renaming it to something different.

Examples and explanations

All punctuation and extraneous words should be avoided. Consider the title:

Alignment: =, Tables, Declarations, etc

The resulting URL is:

http://vim.wikia.com/wiki/Alignment:_%3D%2C_Tables%2C_Declarations%2C_etc

A better title would be (if the tip is about a plugin):

Align text plugin

which has URL:

http://vim.wikia.com/wiki/Align_text_plugin

Remember that a good tip with a bad title is still good, so perhaps your efforts should be spent on improving the tip contents rather than its title.

To change the title of a page, you move the page to one with a new title. If you move a page from Old Title to New Title, the contents, discussion and history of the old page will appear at New Title. In addition, the Old Title page will automatically be changed to a redirect to the new page.

To move a page from Old Title to New Title

• Open the Old Title page (the page with the title that you want to change).
• Check what links point to the Old Title page – see "what links here" in the toolbox in the side panel.
• All tips will have at least one link (from the VimTipNumber redirect page).
• You should change each link to Old Title to be a link to New Title. You will probably only need to change the VimTipNumber redirect page. There is no need to change any pages that link to the VimTipNumber redirect page.
• On the Old Title page, click the Move tab.
• On the Move page form, enter the new title and a reason for the move (such as "Simplify title" or "Remove punctuation"). Read the information including the warning, before clicking the Move page button.

For most tips, as well as moving the tip page from Old Title to New Title, you will need to fix the link on the VimTipNumber page (and on any other page that used to link to Old Title). If you can't find a way to edit the VimTipNumber page, edit the URL below by replacing "123" with the Number of the tip that you moved.

http://vim.wikia.com/index.php?title=VimTip123&redirect=no

Paste the above URL (edited for the correct tip Number) into the address bar of your browser. On the VimTipNumber page, click Edit. You will see something like:

#REDIRECT [[Old Title]]

You need to change Old Title to New Title.

It's worth checking Special:BrokenRedirects from time to time for items that might need fixing.