From: Craig H. <cr...@gu...> - 2006-07-06 18:09:21
|
On Jul 6, 2006, at 7:30 AM, Cliff L. Biffle wrote: > So, in fine Wiki form, we already have duplicated pages on the new > MediaWiki install. Some folks are going through writing up > clarified, organized versions of old pages, while some folks are cut- > and-pasting the old pages verbatim. (Yes, I admit, I'm in the former > group, which is why I'm annoyed.) > > I'd like to try to discourage folks from blindly copying data over > from the old Wiki. If we wanted that information verbatim, we could > simply have stuck with the old Wiki. This upgrade is not purely > about switching implementations. One thing to be careful about is folks who have deep-linked into the wiki from the outside world. We will want as much as possible to not break the wider web as we move over to the new system. I'll do some thinking about how exactly to do that, but we want to reproduce at least all the information which was on the old wiki which is accurate into the new one. > Furthermore, because I'm an expert in overstaying my welcome, I'd > like to propose some editing suggestions for the Wiki. These aren't > official, since I don't work for Gumstix, but they've helped our > Wikis stay coherent where I *do* work: > > - When creating a new page, try to check the Recent Changes link and > look for similar pages. Or, better yet, search -- the search > function works quite well now. > > - When adding information to an existing page, read the page to see > if it might already be there (or be pointed to by a link). > > - Try to make sure that your page links to a few other pages -- and > not just with a bulleted list of links. This is hypertext, not > gopher. Think if a user arrived at your page from a search engine: > how would they find the next info they need on the Wiki? If your > topic doesn't naturally link to a few other pages, it may be > irrelevant. > > - Use the category system! It's in Mediawiki for a reason. > > - Wiki pages are not forum posts. They should not argue with > themselves. Take this example from the "Replacing the filesystem" > page in the old Wiki: > "u-boot doesn't accept Minicom for data-transfer. (Actually it > does; see below.)." > Ignoring the punctuation issues, what does this tell a new reader? > Does it work with Minicom, or doesn't it? Why can't the Gumstix > people just say it works? Who am I? Why am I in this handbasket? > > - Use a modified version of the 80/20 rule. Write the page so it > will meet the needs of 80% of your readers. If 80% of Gumstix > developers use Linux, for example, there's no need to clutter up a > page with directions for Windows and Mac OS X and BeOS and MULTICS > and CP/M. New pages in the Wiki are free! Create one and link to > it. Likewise, if a term is likely to be jibberish to 20% of your > readers, it's worth defining. Remember that a lot of terms on the > Wiki, like buildroot, are specialized jargon. (Pay particular > attention to new readers here; as long as your definitions are > organized, experienced users can always skip them.) > > I welcome constructive discussion on the matter. Bring it on! :-) All the above sounds like very good suggestions. C |
From: Craig H. <cr...@gu...> - 2006-07-06 18:14:24
|
On Jul 6, 2006, at 8:25 AM, James Coxon wrote: > I guess I'm one of the people in the second group though it was > more to get > some stuff in place for me to later refine! (I fear that there is a > risk of > reinventing the wheel and also of missing out really important info > that > perhaps might be missed out due to the lack of personal experience > with > that particular situation such as not having a window box). I think that's a good idea -- my original suggestion was basically to do exactly this, but to make it clear which were old pages vs new by naming the old imported ones as "x_foo" rather than "foo". Then as they're editted/cleaned up/whatnot, they can be renamed to "foo" and "subfoo" and "splinterfoo" dropping the "x_" prefix. That way progress on transferring everything over can easily be tracked by just finding all remaining pages in the wiki which start with x_ > I know you only presented it as an example but the minicom page > shows a > situation where originally it didn't support it but using ckermit > it does > and actually its far better to just us ckermit. It shows the > evolutionary > side of the wiki however it could quite possibly be written in a > better way > - perhaps even an little explanation would be appropriate... Yup -- this is actually one issue which might need some more thought -- over time, the buildroot evolves, and there will generally be 2 versions of the software in common use -- the HEAD and the "latest binary release". Right now, there's a considerable delta between the two. When writing wiki entries which might be dependent on a particular software version, it would probably be useful to note this at the time of original writing, so that when someone later comes through and finds something is no longer correct, they can know whether to outright delete the original text, or put a "this applies to versions before x.y.z" modifier on it and leave it in place for folks who might still need to know. > In regards to the 80/20 rule I think you are discussing the USBnet > page > where I feel that actually leaving it on one page is sufficient and > actually is more helpful rather then forcing people to travel via > loads of > links to different areas - in a sense it is avoiding the over > complication > that can occur with wiki (such as the last wiki!) I think there's probably a balance, on a subject-by-subject basis there will be places where each approach is "correct". 20%-ers get really frustrated when they have to click extra links ;) C |
From: Chris D. <cg...@co...> - 2006-07-06 18:55:26
|
On 7/6/06, Craig Hughes <cr...@gu...> wrote: > Yup -- this is actually one issue which might need some more thought > -- over time, the buildroot evolves, and there will generally be 2 > versions of the software in common use -- the HEAD and the "latest > binary release". Right now, there's a considerable delta between the > two. When writing wiki entries which might be dependent on a > particular software version, it would probably be useful to note this > at the time of original writing, so that when someone later comes > through and finds something is no longer correct, they can know > whether to outright delete the original text, or put a "this applies > to versions before x.y.z" modifier on it and leave it in place for > folks who might still need to know. Just as a totally trivial addendum, Mediawiki's template system seems like the ideal way to implement the version notices. -chris |
From: James C. <ja...@ca...> - 2006-07-06 23:07:00
|
Hey all, firstly Cliff I owe you an apology - Just found your flashing the gumstix page - sorry about adding a tutorial when you had already written one! Secondly should we perhaps move wiki discussion to another place to save most people from the banter or would people rather we discussed it here so that people could easily get involved? James On Jul 6 2006, Cliff L. Biffle wrote: >On Jul 6, 2006, at 8:29 AM, James Coxon wrote: >> Hehe, There is me discussing wikis and docs and my whole post is >> full of >> spelling mistakes - lesson 1 reread what you've written... > >*grin* I won't hold it against you. Making a spellchecking pass is >easy and can be automated; the real key right now is getting >readable, concise, accurate, and complete docs. > >> I know you only presented it as an example but the minicom page >> shows a >> situation where originally it didn't support it but using ckermit >> it does >> and actually its far better to just use ckermit. > >That's a matter of opinion, and one on which I actually disagree. >Kermit's interface drives me nuts, and has since the late 80s. >Minicom can control a Kermit binary quite well, and sticks to a >command set I prefer. > >In my Flashing the Gumstix page, I wrote up detailed Kermit >instructions because I didn't have my main workstation handy, but >this is a case where we should probably present both. However, the >Wiki page should not argue with itself. :-) > >(As for, say, Hyperterminal...I'm curious what percentage of the >Gumstix dev community uses Hyperterminal. I would think people who >run Windows would use a more capable terminal emulator, and those of >us on other systems have different software. Does it deserve to be >in the Wiki? Absolutely -- pages are free. Should it be in the >mainline? I could be convinced either way.) > >> In regards to the 80/20 rule I think you are discussing the USBnet >> page > >Actually, no; none of my criticisms here were directed at specific >pages or users. I hadn't actually read the USBnet page until just >now. It actually looks pretty decent (though within the next year or >two, the 2.6.9 directions will become marginal and should be moved >out of the way). > >I have a couple of changes to that page that I'd propose, but I'm not >an authority on the matter -- I've never gotten USBnet to work with >my Gumstix, only with my other PXA255 systems back on the old driver > |
From: Cliff L. B. <cl...@bi...> - 2006-07-06 23:11:42
|
On Jul 6, 2006, at 4:06 PM, James Coxon wrote: > Hey all, firstly Cliff I owe you an apology - Just found your > flashing the > gumstix page - sorry about adding a tutorial when you had already > written > one! Eh, it happens. I'll merge the two. :-) > Secondly should we perhaps move wiki discussion to another place to > save most people from the banter or would people rather we > discussed it > here so that people could easily get involved? I keep assuming everyone uses a Gmail-like interface and can hide threads they don't care about -- which is odd, because I don't use one myself. Sigh. A separate discussion place might be warranted. I've been using the Talk features on each Wiki page to make notes and suggestions, but that's not great for an actual dialog. -Cliff L. Biffle |