Martin Krischik wrote:
We should not include comments on the content page! That's what the discussion page is for.
You are very keen on that point, so I'm going into a bit of detail about why I don't agree. A wiki discussion page (as you know!) is intended for people to discuss the future of the page. Does an error need fixing? Are there points which need to be expanded? Is the content or style inconsistent with overall guidelines? Or, on the discussion page, I might ask why you reverted my edits, and we could debate whether my wording was better than yours. We'll still need the above in a Vim wiki. However, the Comments in Vim Tips are a different animal. Most comments are fluff, and need to be deleted ASAP. Many comments are very helpful, and their content needs to be merged into the body of the tip. On some tips, a reader would need a lot of persistence to work out what to do, because the tip says X, some comment says Y, and another comment says Z. I think I recall seeing cases where a comment points out that the tip is hopeless because there's a better way of handling the situation. We wouldn't want that comment hidden on the discussion page (where a casual reader won't see it). As I understand it, the whole point of moving Vim Tips to a wiki is so that we can fix each tip so that there is one consistent story on each page. You are correct that having the comments on the main page will be ugly. However, we hope that will be temporary. Perhaps I should say that *I* hope it will be temporary because I see that the proposed sample has a section for Comments. I imagine editing the wiki will go like this: - Import all tips with comments on main page. - Edit important tips and clean them up completely. - Edit nearly all tips to remove junk comments. - Leave difficult cases for later. I imagine there will be lots of difficult cases where considerable effort would be needed to merge the comments. In those cases, we would just leave the useful comments, perhaps editing them where helpful. Later (say in six months) we would discuss what to do with those tips that still have unmerged comments. In some cases, it might be very reasonable to leave comments on the main page. For example, a tip might describe a scenario and its solution. Then a comment might say that if you are running on a certain platform, then a better approach would be something else. It may never be worth fixing all tips to eliminate such comments, yet you wouldn't want to hide that useful info on the discussion page. I think that following the above strategy would be much easier for people editing a tip (easier than editing the main page and the discussion page, because once a comment is dealt with, it would have to be removed from the discussion page). Also, seeing the old comments on the main page would be an immediate reminder that the tip needs cleaning up. Imagine the mess if comments were on the discussion page, then someone edited the main page to include a few useful comments from the discussion page, but failed to remove those comments. It would then take herculean efforts to properly fix the tip, and the discussion pages would have so much junk in them that their function as a tip discussion would fail. John
