Wiki Editors and Policies

PaulStoffregen

Well-known member
With the upcoming addition of a Wiki, I'd like to discuss roles of editors and policies for editing content. Please keep this thread about editing & editor roles. Use the original thread for general discussion of the wiki setup, and this thread Defragster started for specific content suggestions.

Arduino's wiki, I believe, is a great example too little editing for a massive amount of content. Much of it is outdated, and finding anything involves very long lists of links, many with poorly composed descriptions. We may never have nearly that much content... but I'd like to plan for success.

I've made minor edits to some pages on Arduino's wiki. I've watched as others did the same. Usually the tendency when editing an existing page is to tack on some extra stuff. Almost nobody deletes anything on a page, even if it's obviously outdated info, where they're not the primary or original author.

To really make this work, I believe we need some designated editors who are empowered to make substantial edits to any page. Maybe some edits will look like the stuff seen on Wikipedia, where an editor adds a colored message like "the following info may be outdated, please update it if you know the material". I don't believe we need rigid style guidelines like Wikipedia, especially at the content page level, but we really do need dedicated people who are entrusted with being able to edit pages. They shouldn't feel inhibited to simply delete stuff that's obsolete. They shouldn't need to ask for anyone's permission to make substantial changes, like breaking a page into two separate ones, or consolidating 2 pages, or a variety of other pretty meaningful changes to the original content.

The information architecture is also an area where we really need editors. I do not believe anyone can envision in advance exactly what the top-level and mid-level categories need to be. It's going to change over time as the wiki grows. Restructuring things takes initiative and risk. Descriptions and links often need to be made more clear. Again, we really need some people who are designated to make those decisions.

There may be all sorts of other issues too. The honest truth is this is my first time trying to set up and establish a wiki, so I really don't have a good feeling for how all this stuff should work. What I do know is wikis on other sites usually have too little content, or far too much content that feels like an unstructured mess. Let's talk about these issues and how we can administer this wiki as well as possible.
 
I agree that the best approach is to designate someone for each section as a housekeeper. I'd be happy to share my experiences / suggestions making a hardware derivative of the Teensy, for example. Pedevide would be a natural choice for his ADC library. Etc.

Editors should be free to create sub-pages / sections. For example, the Wiki could have a general hardware page that discusses the hardware at a top level (i.e. the comparison chart in the store). Then each family of Teensy's gets a sub-page dedicated to them. Within that page we would list details specific to the hardware (i.e. BOMs for roll your own, etc.). If the sub page becomes too cluttered, then it would be split again among multiple sections to keep the content on point (i.e. using an outline approach) and limited.

If that seems reasonable, I'd suggest you give us guidance re: the maximum length of a page, etc. so we can maintain a pretty cohesive look across the wiki (that is, all editors follow the same rules of thumb re: content length, depth of discussion, and so on). Lastly, if we plan categories in advance (we know the Teensy pretty well) then some of the issues re: re-organizing later will likely not happen.

For example, the ADC section at top level might have one category where the hardware of the Teensy ADC is discussed. Subsequent section would focus on the software (Pedevide, et al). Another similar set of sections would discuss interfacing Teensys to sensors, arranged by type (pressure, current, etc.) and interface (analog, I2C, SPI).

If we parse this sort of stuff out in advance, I'd like to think that the massive re-organizations may not need to happen often in the future.
 
+1 for section editors. Would it make sense - without doubling the work/content - to have a parallel Forum thread (per-section) for chit-chat-suggestions with the section editors - that would keep the wiki clean and consistent per section, and give a way to question/suggest content without someone making a change when they were mis-interpreting content/placement? That would put onus on Editors to resolve those issues, and allow content to be uniformly directed/added and be benevolent dictators - rather than playing wack-a-mole/musical chairs with content blocks. For instance post#1 on ADC thread is the initial Wiki Page - section editors could start such a thread to gather content before the wiki is online to flesh it out - and then edit post #1 to 'Go To Wiki URL' when it goes live, and the wiki could point to that 'thread for chit-chat/suggestions'. That forum Section Post #1 could also be a "Section's rules of the road" as some wiki subject areas won't be helped by user input. That would also keep life in the forum as the wiki could point folks there for dynamic help when they get stuck.

Is it going to be generally open to forum participants for edits? [pros and cons there]. An editor as admin could have full access in early days before (locked out) users could countermand them, but users could do forum thread feedback.
 
I think the hierarchy should be as follows: Paul and Robin as a benevolent dictators, able to add/delete whatever they want and add/revoke user's privileges. Users can be "section heads" (more than one per section would be ideal) and are in charge of that section, able to create/merge/combine pages as the content develops. Then the rest of the users may add/edit/delete stuff from each page, but nothing else.
I don't know if that granularity is possible, and different schemes can work as well.
 
Is it going to be generally open to forum participants for edits?

That's a very good question. I don't have a definitive answer, but I do have some thoughts...

Nearly 20 years of history with Wikis shows they work best when almost anyone can create and edit the pages. Yesterday Robin and I were talking about using the vbulletin user grouping or "levels" (or whatever they call it) so everyone would automatically gain access to editing the wiki after a certain number of forum posts. What that threshold should be is a good question. I was thinking something pretty low, like 25 to 50, or maybe even lower. Robin was thinking a little higher.

My hope is everyone (at least everyone above some message threshold) can and will create wiki pages. Anyone with access should be able to add a page, or add content to almost any page.

Pretty much anyone should be able to step up to act as an editor too. The main point to having editors is we really need a small core group of people who are empowered to edit and reorganize content, and to flag or delete outdated stuff. Without editors, there's a pretty natural tendency to be too polite, too reserved about changing someone else's content. Especially maintaining the overall organization and top-level categories and structure is a task where editors need to exercise some control and make not-always-easy decisions.

I'd like to publicly recognize who the editors are. They're the people we should all expect to come in and post a notice that some part of a page may need improvement, or to make a tough call to consolidate two pages, delete outdated stuff, or to restructure the hierarchy. While the system will technically allow anyone to edit anything, as a social convention, most people usually create new stuff or make small additions. We expect the editors to make substantial changes, to take bold actions, or risk public ire by attempting a restructure of some part of the hierarchy, or to make the call to undo someone else's changes (the system keeps a history off all prior versions of every page). Editors are about community recognition of their responsibility to make these sorts of decisions. Anyone can edit the wiki, and indeed everyone is encouraged to contribute, but we expect the editors to make the not-so-simple editing decisions!

We might also need a little tighter policy about promoting products and especially Kickstarter campaigns via the wiki. Currently pretty much anything somewhat related to electronics is allowed on the forum (perhaps with snarky replies). Some threads have pushed the envelope slightly, but generally we only delete and ban the really blatant spam. I don't want to censor too much, but I would like to at the very least ban not-yet-funded crowdfunding campaigns from the wiki.
 
Last edited:
newbies should have at least read-only on the wiki
Yeah, it would be kind of pointless if the main pages are not visible. I can imagine having pages controlled by ACL (access control lists) or similar to allow people to put up pages, and review them, and then publish when they feel they are ready. It could also be used for communication with alpha testers before the Teensy 3.1++/4.0/whatever specs are public.

And of course Paul/Robin should have the ability to revoke somebody's write access. I recall back when I still read the Arduino forum, there was one user that seemed to specialize in posting harmful information.
 
Generally you don't need to even log in to read a Wiki - though that is adjustable.
Perhaps the tie to the forum for discussion on content/edits only sounded good in my head - maybe a sub page/section in each area where a pending/proposed page could be populated for review/integration/refinement. That could be a more relaxed way to invite 'ready to use input' that might never go live in that form.

<edit> outside link policy?
I just added this line to the request for wiki links:
Need not be limited to FORUM posts - I see GITHUB links for libraries - and for areas with definitive outside info that lets hardware work under Teensy. Outside links can go stale - but when the wiki comes together that can be considered then if posted now.
Perhaps outside links going stale will be fixed with a living wiki? For instance I linked to a nRF24 page today and somebody went from 5-15ft with losses - to no loss at 50ft. As a user I could copy the key bits to the forum and put the outside link there (of course I don't know the future user problem) - and then wiki link to forum? The forum could hold more extraneous background, but even more likely to go stale as not editable by everyone.
 
Last edited:
The less time, thought & keystrokes needed to make a contribution, the more there will be, for better or worse... I guess the trick is the balance between volume of info, and quality; and how much you rely on editors to reorganize and weed, vs. some wiki structure that encourages a clean and useful style to begin with. If that is even possible. Personally, I make some attempt to match the style and organization of what's already on a page. So if you start out with some material in a good format, that should help additional info to crystallize out of the soup. To strain a metaphor.
 
Making it all glue together will probably not be possible but my thought would be wiki pages with a formal content section and a comments/errata text field at the bottom that is more freely editable (smaller number of forum posts to make an edit) and if possible setup for generic spam blasting (so managers pull useful content then flush everything else on all pages they manage).

As noted above, idea being to make adding notes and thoughts easy, but with the expectation that they will be wiped for major version changes, time or because the box is cluttered unless you take the time to proof read, edit and format into the formal page structure.

Almost the same effect can be had with a forum thread for each page, but means it's harder to see since they won't be on a single screen, unless your wiki software is really clever and embeds the forum thread below the page. The wiki style comments page isn't as useful in this case since it's hidden from sight by default and we want to maximise the chances of somebody using the wiki getting their eyeballs onto the trick/tip/workaround they need on the first page they hit.
 
Nearly 20 years of history with Wikis shows they work best when almost anyone can create and edit the pages. Yesterday Robin and I were talking about using the vbulletin user grouping or "levels" (or whatever they call it) so everyone would automatically gain access to editing the wiki after a certain number of forum posts. What that threshold should be is a good question. I was thinking something pretty low, like 25 to 50, or maybe even lower. Robin was thinking a little higher.
Of course quantity of posts does not guarantee quality of input, and vice versa. It's pretty frustrating wanting to correct or add some information to a page, be it a wiki or a thread, and not being able to because you're not a member of the specific forum. I use a lot of different electronic resources, but almost never register anywhere. A minimum post limit is a filter, but imo a rather rough one.

I administer a large forum myself (over 10k registered visitors a day), and for special sub-fora we use custom usergroups (the forum software itself is Vbb too). Our moderators examine and approve the join requests to these groups, and keep an eye on the newly joined. If you have an active moderator community, this can guarantee the quality better than a static filter. In case of this community I think the ratio of active editors (who will need to approve wiki contributors) to contributors will be more than favorable enough to make a system like this work smoothly.
 
If you have PHP experience (good if experience with MW or xF PHP in particular) and you would like PJRC to (at least be able to) consider MediaWiki as a candidate for their new wiki then please PM me - the MediaWiki xenForo bridge isn't quite as 'far back' as the bridge for vB but I am concerned that I may not manage to fix it (enough) for the current versions quickly enough to 'get it on the table' in time to allow decent review of it before those guys feel the need to proceed with something.
 
Back
Top