Wikia

Vim Tips Wiki

Vim Tips Wiki:Comment guidelines

Talk0
1,612pages on
this wiki
Revision as of 14:06, April 13, 2009 by Fritzophrenic (Talk | contribs)

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

  • Nearly all comments should be removed. But don't delete anything helpful until it has been merged into this or another tip.
  • Keep it simple. If a comment is worthwhile, it should be merged into the body of the tip. You may end up with several ideas on how to do one thing. Try to use your judgement, and delete the less attractive options
  • The longest journey begins with a single step. Significant work may be required to merge all useful comments into the tip. It would help if you just merge some useful comments into one.
  • Be on topic. If a comment is useful but not relevant to the tip, it should be moved to another tip (paste into another tip; delete from this tip). In practice, it may be difficult to find another suitable tip. In that case you could just clean up the comment and leave it.
  • Simple is good – when in doubt, leave it out. If a comment does not help someone wanting to use the tip, please delete it.
  • The perfect is the enemy of the good. Someone else may do a better job. But they are not here – if you think it's worthwhile, do it.
  • Delete all author names and dates from comments (but we keep these for a few weeks when a new comment is added). All comments in the tips imported from vim.org have been at least partially cleaned, and names/dates have been omitted. When expressing an opinion about what should be done with a tip, it is appropriate to sign a comment (by adding ~~~~ at the end of the last line). However, we aim to clean the tips, and eventually all opinions and names/dates will be removed. On a wiki, authorship is attributed only though the History of each page.

Examples and explanations

In general, comments are of different kinds:

  • Misguided advice Just delete it (put a brief and polite explanation in the edit summary).
  • Thanks, this tip was very helpful We might keep this for a month on a new tip, but it's a distraction that should eventually be deleted.
  • Here is a better way of doing it... This should be merged into the tip. If there are substantially different methods, the variants should be in separate sections.
  • Opinions on improving the tip Fix the tip and remove the comment, or improve the comment and leave it.
  • See also... References might be handy, but please confirm that they are useful for this tip because everyone already has too many "must read" links. Many tips now have ==See also==, ==Related scripts==, and ==References== sections. Consider placing really useful links in these sections, using a bulleted list.

Around Wikia's network

Random Wiki