From Vim Tips Wiki

Can anyone still follow this discussion? Tom and I would like to use the vim-l list for wiki-related issues and vim@vim.org or the talk pages for vim or tip related issues. I hope that you guys will join vim-l. The listinfo is here: http://lists.wikia.com/mailman/listinfo/vim-l . In any case we should write from time to time on vim@vim.org to attract the readers there.

Thanks, bastl

---

1. Should we keep the tips pages in roughly in the old VimTips format: an initial Tip, followed by discussion and improvements on it? Or is the ultimate goal to have something more like a small 'Tip Article' which would present all the relevant information prompted by the original tip in a logical order, including references at the end of the article? (See Mapping for quicker access to macros for a simple but nice way to do references to Vim's internal help. This should be standard in all articles.) I ask this because the Vim Tips Wiki:Golden Rules says that "After some time all comments should find their way into the main tip." But the review template seems to imply that the goal is to just "clean up" the comments.

I like the idea of migrating the old tips into Tip Articles, with a structure that befits the topic, since that's what you'd normally do in (and want from) a Wiki. This would mean we would encourage editors of the Vimtips to condense, re-arrange, fill out, and to add references to vim help as appropriate. And they would generally migrate the comments as they saw fit. (Sometimes it might be useful to preserve the original line of discussion.) But all this would be entirely up to the Wiki-editors of each individual tip. True?

2. Of course this raises the question of what to do with all of the original contributor attributions. To include all commentators in a thoroughly revised article would be both too much clutter and too much work. Original authors of quality tips should, OTOH, still be given credit (I guess), even (probably) if subsequent revisions morph most of their work beyond recognition. They had the original idea. They submitted it to an attributed forum, and it spun off a certain amount of discussion. Keep their names and creation dates. It's not the Wiki way (generally), but there's no harm in it and, it was the old VimTips way.

Of course the awkward bit is that if we just leave the header untouched then the "Created" date in the header (which used to apply to the original tip as distinguished from any amendments), is now out of date with any substantial revision. If a tip is revised to include the latest on a new Vim version, the date is a little confusing (though of course it does say "Created" and not "Last Edited"). Would it be worth it to add a new header element which would communicate something like: "Edited to refer to: Vim 7.x" or "Includes: Vim 5.2-7.1" or whatever?

3. One final question: Could that header line (Created: Complexity: Author:, etc) be visually offset somehow (or reduced in size and/or colored)? It usurps the head of the articles, visually. It would be nicer if the overall layout drew the eye first to the article title and after that to the first words of the Tip itself.

Simply edit Template:Tip the way you like it. Perhaps that discussion could be taken to Template_talk:Tip :-) bastl 12:31, 11 June 2007 (UTC)

Sc.becker 11:50, 9 June 2007 (UTC)

Let me add to that and ask whether we want these new Tip Articles to be themselves 'forums' for the discussion of the tip (therefore every tip should keep a 'Comments' section at the bottom, whether it is yet to be filled or not) or whether we should just treat them as Wiki articles: edit according to our experience and best judgment, and discuss it if necessary in the 'talk' pages?

(a little later) I've been perusing and seen that in many cases it probably is not the best thing to take the old VimTips discussion and turn it into an article. For example the post Don't use the escape key! not only has several suggestions beyond CTRL-[, it leads into a whimsical discussion of other ways one might switch modes in everyone's favorite modal editor (foot pedals, modified keyboards, bite switches). Of course it's fluff, but what later editor would want to mess with 'Vim users at play'? On the other hand, simple tips with a few corrections or suggestions for improvements are perfect candidates for Wikified editing. Get the goods on the table as quickly as possible, chuck the discussion . Posterity will thank you. Any insight on this? Wiki really is a different medium that that old VimTips forum.

Sc.becker 13:25, 9 June 2007 (UTC)

These are excellent questions! I tried to discuss some of this in the vim@vim.org mailing list but I think people were wearied by the endless planning, and just wanted to get on with it.

I hope to propose on the mailing list that a page be dedicated to discussing your points -- a page that would be edited to show the current recommended procedure, rather than the "Your Comments / My Comments" of a forum page like this. My quick opinions on the issues follow.

We should mostly keep the tips as unrelated offerings because trying to organise everything at some higher level is too much work, and would give pages that are too long for people to want to absorb. I don't think there's much point in making "articles" - why reproduce Bram's documentation?

But we should NOT try to maintain the original tips. Example: Tips 1 and 5 discuss using * for searching. They must be merged (if they're not, this whole exercise is pointless IMHO). If I looked, I would probably find another half dozen tips on searching - they should be merged or linked (but practically no material should be duplicated).

After thinking about the above, and contemplating what a reader is going to want, I favour just completely removing all attributions (that is, delete the author of the tip). Look at the extraordinary work in wikipedia - I can see a detailed article on biology, say, (MUCH more than one or two lousy Vim tips), yet there is no credit to the author. I would like a special page which simply lists all the original tip titles and author (and maybe date). We would not update that page with new authors (although it would be ok if an author wanted to add themselves). We would not try to keep links from this list to where the current tips are (too much pointless work).

We need an "ideal tip" - one with the section on Help you mentioned, and with all other points addressed. That would be how we would like other tips to be.

I don't like adding "Edited to refer to: Vim 7.x" or "Includes: Vim 5.2-7.1" etc. Whereas that might be nice, I think a dose of cold reality is required. It's well over two months since putting the tips in a wiki was seriously planned, there are over 1500 tips, and there is very little happening so far.

First, it's just too hard telling someone using Vim 5.2 which tips they can't use. It's not going to happen. Second, it's too much noise in the tip page. Third, the only kind thing to tell any user of an old version is "See Tip XXX on how to upgrade!".

Re the whimsical articles: I favour keeping any with sufficient innate quality. However, it would have to be a great piece of writing with something to say. For 99% of cases, I favour deletion. If the number of tips keeps growing, there is simply no reason to keep the tips at all. Imagine thinking (say) "I wonder what emacs is like ... I think I'll look through their tips page". Then, say you found such a page and saw a list of 2000 tips. I'd think "OMG what a bunch of nutballs".

Re the Comments section: My strategy is to delete all redundant comments and all signatures. Edit other comments if required. Aim to merge all comments into the article. Don't bother if a comment is too hard to integrate, but has something useful to say (e.g. "On Linux, doing xxx would assist").Keep the comments section in case someone wants to add a point to the content, but doesn't want to merge their opinion into the main tip. Later, we might merge the comment, or we might leave it.

I favour putting pretty well all comments on the tip page for the next couple of months. Example, on Tip 5, I put comment "TODO: Merge with tip 1". If I put that in the discussion page, no one would see it. We have 1500 pages to fix - let's not make it 3000 by putting comments in the discussion pages at the moment.

JohnBeckett 08:50, 11 June 2007 (UTC)

---

Ah, im sure your points are good, but i cannot stand this forum for longer threads, sorry :-) I've proposed to move such discussions to this list: vim-l@wikia.

My two cents: On the one hand I would like to refactor the tips to remove noise and get really good quality. On the other hand a lot of comments like "very good tip" will attract other ppl and gives the whole thing a personal touch. I also like the fact that the vim community is fairly old: VimTip1 is of historical interest in my opinion. Even the arabic glyphs though I cannot read them ...

bastl 09:40, 11 June 2007 (UTC)

---

Uh oh - I've already zapped the comments in Tip 1! Feel free to revert, if you insist. I take your points re the historical interest of Tip 1, and the chatty nature of the old tips page.

No problem. The old tips are still available at vim.org. With that in mind, it will be ok to remove noise. But what about the nice comments like "that tip saved me hours of stupid work" Its also advertisment for vim itself. -- bastl 12:28, 11 June 2007 (UTC)

But really, what are we here for if we leave the tips as they were?? I've spent quite a long time editing a very small number of tips (only superficial clean-ups). We need to quickly agree on a strategy IMHO.

I agree completely! that was the original idea of the "Golden Rules" I started. Perhaps we need a wiki page on the "Strategy" !? Wikipedia has a nice (and extensive) Manual of style. I think we need something similar, not that extensive, but simply a good guideline for contributors on topics like disambiguation and the like. Concerning Disambiguation: We have the inverse problem: Many pages on the same topic. How to proceed in that case? Your "c.f." idea is nice. but there should be a standard way ... bastl 12:28, 11 June 2007 (UTC)

Yes please - make a policy page, and let's edit it according to current community feeling. I think it should be prescriptive (in a friendly "you can ignore this if you want" way), rather than a back-and-forth discussion like we're having now - which is confusing. JohnBeckett 23:00, 11 June 2007 (UTC)

This is the first I've heard of your mailing list ... does there have to be another one?? Bram seemed to want the wiki tips to succeed, so let's use the vim.org lists and too bad for those that don't care. If you start a new list, you'll only get 10 or 20 people. It would be good to ask everyone on the vim.org list to comment on how tricky tips should be fixed.

JohnBeckett 12:06, 11 June 2007 (UTC)

Dunno, it doesnt have to, but I thought that all the VimWiki- posts are not on topic for the list vim@vim.org. bastl 12:28, 11 June 2007 (UTC)

You are correct of course, but after a small number of policy matters are discussed, we'll only be taking the vim list time to discuss particular tips - which is on topic. Also, we need to promote the wiki or we won't get enough critical mass. JohnBeckett 23:00, 11 June 2007 (UTC)

Thank you, John and Bastl for your replies. I am convinced by: (1) not turning VimWiki into a replacement for Vim's existing docs, which are quite good, but keeping the ad hoc and functional nature of the Tips style (2) not keeping the existing tip structure of submission and comment (generally, people should be encouraged to merge there comment in, even if it's just adding to a list of 'other ways to accomplish the same thing' or 'changes for Vim under OSX') (3) merging all comments, unless there is a very compelling reason to keep them, whimsy be damned. You are right. Lengthy forum style chats are only fun to read when they're fresh, and sometimes not even then. A year later you just want to get the information as efficiently as possible. (4) merging any duplicate tips, or splitting out tips that sprawl, and even carefully (5) deleting tips which really aren't that great, so we keep the cruft down. Obviously this must be done carefully and by someone whith good judgement and fairly wide experience. But I don't think that should keep us from doing it. (6)And you're right, John, maintaining version numbers is too much work, though in that case I'm for nixing the headers created from the old tips, (with date, complexity, author, karma), or at least moving them to the bottom with the prefix: "Original tip "[Created on...] if you want them for historical interest. But if we really want a Tip Wiki, as opposed to just a transported version of the old forum-style tip database (which I think we do), those headers have no real place in the article. It is a minor shame to loose karma, but it can't be helped, and we should probably just cut bait and not look back. People can make a 'top 10 tips for [somepurpose]' page if they like, which I think is a good idea. (Like Amazon lists, such pages could be a human-created guide to the gold, as the list-maker sees it.)k

It's true this forum is a bit naff, and I would certainly be willing to subscribe to another list, but the forum is here, and it has that in its favour. Contributors to the wiki are already subscribed and have the same names as those on their edited pages, which is worth something. We can easily link to examples and, create working samples, all the things that Wikis are good for. I'll follow, but I don't mind just staying right here.

And sure, all comments can go on the tip page for the next few months. For the same reason.

Sc.becker 20:24, 11 June 2007 (UTC)

Wow Sc - you might be the only sensible person I've met on the Internet<g>! We seem to agree on everything! Particularly the concept that whereas we fanatics might enjoy whimsical comments, someone trying Vim just wants the info.

However, I don't really like the idea of a new mailing list. We need help here! Therefore we should post problem cases in the vim mailing list. We can put (say) "Wiki" to start each subject so objecters can filter us out. I have a strong hunch that if we post a problem like how to clean up tip xxx, we'll get some good answers, and will attract the occasional editor. Contributors would get more buzz from posting a careful reply to the vim list, than they would from coming here, making an account, learning the basics, then editing the Wiki (which only one or two people might notice in the next month).

JohnBeckett 23:00, 11 June 2007 (UTC)