(reworked: added "in short", reformatted quotes (i interpreted them as headlines for the following paragraph before ...), add examples and explanations.) |
JohnBeckett (talk | contribs) (Minor reword of new material.) |
||
| Line 1: | Line 1: | ||
| ⚫ | |||
| − | |||
{{NavPolicy}} |
{{NavPolicy}} |
||
| ⚫ | |||
* '''Nearly all comments should be removed.''' |
* '''Nearly all comments should be removed.''' |
||
| Line 17: | Line 16: | ||
== Examples and Explanations == |
== Examples and Explanations == |
||
| ⚫ | The comments were difficult to migrate from http://www.vim.org/tips/index.php because we switched the medium. Before, we only had static entries and comments. Using the wiki, we can do much more powerful things. To express that a tip is very good, rate it. To fix a typo, edit it. To add a reference, edit the tip. Therefore the general rule is to get rid of all comments. If a comment is valuable, move it: either into the main tip or to another tip, or even a new one. |
||
| ⚫ | |||
| ⚫ | |||
| − | |||
| ⚫ | |||
| − | |||
* '''Spam''' This is clear to be deleted. |
* '''Spam''' This is clear to be deleted. |
||
| − | * '''Thanks, this tip was very helpful |
+ | * '''Thanks, this tip was very helpful''' Nice to know, but no real content. Should be deleted. In some cases the history of comments is interesting to read. For example, see the [http://vim.org/tips/tip.php?tip_id=1 original VimTip1]. |
| − | * ''' |
+ | * '''Here is a better of doing it ...''' This should be merged into the tip. If there are substantially different methods, the variants should be formatted nicely. |
| − | * ''' |
+ | * '''See also ...''' A list of references at the end of a tip is always nice to have, but please confirm that they are on-topic and useful. |
Remember that each imported tip has a link to the original tip, where all the original comments can be seen in their full glory. So don't worry about removing them from the wiki. |
Remember that each imported tip has a link to the original tip, where all the original comments can be seen in their full glory. So don't worry about removing them from the wiki. |
||
Revision as of 01:16, 1 August 2007
In short
- Nearly all comments should be removed.
- 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. Later, someone else can merge what remains into the tip. You don't have to fix everything in one session. Your work is appreciated even if you just clean up one comment, or fix one typo. However, please don't waste time fixing comments that are noise, or which are peripheral to the point of the tip – just delete them.
- 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. Perhaps insert a line at the top of the comment: TODO: This should be somewhere else.
- Simple is good – when in doubt, leave it out. If a comment does not help someone wanting to use the tip, please delete it.
- Delete all author names and dates from comments. There may be one or two exceptions, but generally we can't attribute authorship, and the tips would be too unwieldy if we did.
- 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.
Examples and Explanations
The comments were difficult to migrate from http://www.vim.org/tips/index.php because we switched the medium. Before, we only had static entries and comments. Using the wiki, we can do much more powerful things. To express that a tip is very good, rate it. To fix a typo, edit it. To add a reference, edit the tip. Therefore the general rule is to get rid of all comments. If a comment is valuable, move it: either into the main tip or to another tip, or even a new one.
In general, comments are of different kinds:
- Spam This is clear to be deleted.
- Thanks, this tip was very helpful Nice to know, but no real content. Should be deleted. In some cases the history of comments is interesting to read. For example, see the original VimTip1.
- Here is a better of doing it ... This should be merged into the tip. If there are substantially different methods, the variants should be formatted nicely.
- See also ... A list of references at the end of a tip is always nice to have, but please confirm that they are on-topic and useful.
Remember that each imported tip has a link to the original tip, where all the original comments can be seen in their full glory. So don't worry about removing them from the wiki.