Comments on BetterWikiDocs

Ladder of trust

(Suggested by DuncanLithgow)

The end solution must make clear the level of expert participation in each type of documentation. A possible structure (for Edgy Eft) is:

• Official docs: http://help.ubuntu.com/edgy_eft/ (user comments allowed on each page but moderated by doc writers, informative ones get added to community docs. Adding comments is the lowest technical barrier to new users.)

• Community docs: http://help.ubuntu.com/edgy_eft/community/ (wiki based docs - can be linked from comments in the official docs. Structure would permanently mirror official docs, but allow for the creation of new sections. The pages would initially mirror the official docs - then see where it goes. Community docs would then provide ideas for the next set of docs while remaining version specific. Active until end of support cycle.)

• Ubuntu+1 docs: http://help.ubuntu.com/ubuntu+1/ (current snapshot of official docs for next release. Including the ability for user comments (doc-team moderated) to remain between syncs with the offically developed docs. On official release date this directory could simply be renamed.)

RobertStoffers

The hosting of HTML on the wiki is awful to edit, it is all over the shop with no uniform indentation or separation of, well, anything. A dedicated docbook editor would be much more efficient and generally nicer than this (eg Sarma), discussions of my intended project to address web-based editing are currently taking place on the Doc Team mailing list, see this email and this other email for more information.

Engla Feature Request: Page branching, to make it easy to update a documentation page to reflect the new release, while the release is being tested and developed. We want to serve documentation pages that are up to date and specific to the ubuntu release the user has. We should: * Provide an interface for the user to switch between related branches of the same topic. * Provide an interface for authors to work on new branches in preparation for a new release. This should (or not?) be visible to only a selection of users, for example logged-in users.

DavidTangye

I agree with the sentiments/ideas expressed in BetterWikiDocs WikiLicensing and the above. So far you have made a good job of merging duplicate stuff ( MergerPlan ). Now we need to go the next step to get better documentation built more efficiently. We need to all clearly understand, agree, and have stated clearly and unambiguously the goals/objectives, ahead of implementing effective and efficient workable solutions (eg as per in italics).

For example.

1. Improve the quality of the content
   1. Improve the presentation of the info
      • Provide more visible and useful common layouts, eg

        • improve/enforce templates or

        • have more people going round pouncing on spelling mistakes, missing words (eg like "the") and beating layout disasters into shape

2. Ensure correct, up to date and appropriate content within topics.
   1. Improve the currency of the information, eg

      • set up an environment conducive to getting good info ripped out of mail lists and into the wiki ASAP... certainly faster than currently. In fact its a sad fact that there is a heap of problems and great advice in mail lists etc that come up time and again, and still the solutions do not find their way into the wiki... and I do not believe the fault is anything about any technical failing of the wiki concept... Its about people not performing. One way or another, people need to be made / allowed to perform.

3. Devise strategies to fight redundancy of info / duplication of effort / waste of energy
   • Come up with at least a statement of understanding as to
     • what types of information mastering, production and dissemination mechanisms and facilities Ubuntu and its people support and use, and more importantly
     • what types they do not cater for, eg tex?, dvi?, MSWord? format, whatever.
       • In other words, scope your world and focus on what is achievable with the limited resources you have.

Some possible things to consider as part of the solution.

1. Specifically discourage some specific things, eg
   1. Howtos What is so special about them? If all documents have a structure say like:
      • Abstract stuff (high level why are you here, etc)
      • Specific stuff
      • Other references/reading/footnote stuff

      then a HowTo is just another document/wiki page which focusses more heavily on the "Specific stuff". Maybe there should be encouragement to instead call those type of sections "HowTo" within any document if that is what is appropriate.

   2. references to man pages in user documents.

   3. Using emotive phrases, or those that reflect your own capability: eg "Simply edit this file, just write Edit this file

   Anyway my point is that the more clever and encompassing our entire document strategy is will ultimately determine how good documentation will be.

   To go forward more effectively we need to link document types to types of end-users more clearly. We also need to focus more on non-computer-literate end-users. Do we accept that they do not have the knowledge nor interest to use a terminal window? Or can we assume they can and must be able to enter commands. (I used to think not, but hey, if they have a keyboard in front of them (do they?) then why cant we assume they can use it?) Whatever is decided, this needs to be expressed clearly, and documents must explicitly state the level of literacy they are targetting.

suggestions from brallan

I get the sense that this team is doing an amazing job, but that there are too few people involved. I believe that the best way to improve things would be to get more people involved. Do you agree? I sense a hint of nervousness. What will happen to the documentation and the wiki if we really encourage the whims of the vandalous throng? Well, I think there are many paths a wiki can go down, but I think we can learn something here from wikipedia and Nupedia. Nupedia favored professionalism and expertise, and Wikipedia favored the throng. I believe wikipedia succeeded in producing the more useful set of documentation for that simple reason, and I will describe it below. But in general, I see a general lack of interest in the wiki on the forums. I rarely if ever see a post that mentions a wiki. Here's what I think we can learn from wikipedia:

At present, users are required to create an account to edit the wiki. While there has been talk of unifying the login accounts, i don't think this alone will really be enough. While login makes sense in a forum, it is a mistake in a wiki, which already has enough to deter potential editors as it is. Anyone can shoot off an entry to a forum, but to edit a wiki you need to know markup. While login hardly seems like a big deal to those of us who already have an account, we should remember that the magical interest in a wiki is created AFTER the initial correction of things like spelling errors, small and spontaneous edits that do NOT require knowledge of how the markup works, etc. This is what piques interest, and then, upon seeing the edits go through, one gradually learns the markup, NOT the other way around. No one is going to make an account merely to fix a spelling error. Almost all wikipedia editors start out as guest editors before getting hooked and often only much later realize there are advantages to having an account.

But I see that there is often resistance by a group of experts like yourselves to the leap of faith that wikis DO work better when run by a large group of nonexperts than a small group of experts. It raises the spectre of spending all day recorrecting your work, and being constantly frustrated at seeing incorrect information spouted forth as fact. What we need to realize is that human knowledge is a collective act. Here's an anecdote to illustrate. I lived in Turkey for three years. When you ask for directions on the street, the person you ask may not know, and not knowing, they won't let you go, but insist on ask another person for you. If the second person doesn't know, they'll talk about it for a while and then they suddenly know, and they turn to you and tell you how to get there. Now, would you trust two people who didn't know to get together and tell you the answer? I didn't have much choice, but when people did this they NEVER LET ME DOWN. Thats why wikipedia works, and why we need to get more people involved. Please make the leap of faith, at least as far as putting the issue (of login vs nonlogin wiki edits) to a vote on the forums.

Here I came across some forums users who decided not to edit the wiki for the reasons stated above.

Now, one could argue that uniting the two accounts would solve this, by allowing access to all of the ubuntuforum members, but let me ask this - How many of us edit the suse wiki or the Mandriva wiki or the fedora wiki? the answer is probably none of us, and though part of that is because it's a different distro, suppose you only occasionaly (every month or so) came across something in there of interest or that you saw needed some kind of update to it. Well, now you need an account. Will you remember the password, and each of those maybe were different logins. Chances are you won't take five or ten minutes to register or ask for the password which you've forgotten sent to you, relogin, etc.

The point is, for every vandal or ignoramus we're trying to keep out there's a much greater number of folks we're scaring off before they even develop an interest. And in reality all that's usually needed is a nudge towards the www.uncyclopedia.com uncyclopedia (you'll never see that vandal again!) or a gentle reminder of the guidelines to editing.

In my opinion, the ubuntu wiki interface is also not the best, I'd far prefer the mediawiki (wikipedia et al) ware. If there are advantages to the ubuntu wikiware, It's lost on me, as of yet. Even if there are, its annoying to be asked to learn a new markup language which is not even consistent with the forum's markup, and makes it particularly confusing to go back and forth, since they have a very similar theme and you forget which one you're in. I could be completely wrong about all this, but unless there are some really good reasons, I'd like to see it put to a vote in the forums.

To better integrate the wiki and the forums, here are a few ideas (hope im not repeating old ideas yet to be implemented):

it'd be great to see a search bar included on every wiki page for both the wiki and the forums and one on every forum page for the wiki.

There also could be a simple option at the bottom of any thread which would allow users to add a wikilink to any thread, so that it at the top of the thread, a reminder appears, either saying Related Wiki(s): or The wiki realted to this thread needs work:

Until this is implemented, one could simply add notes to (particularly informative) threads encouraging additions to the wiki, and by putting a reminder at the top of the thread that there is a corresponding wikidoc should be sufficient.

I agree that we should be removing the "HowTo" suffixes from articles - almost everything in the wiki SHOULD be a howto, since that's what people are here to find out. If you're answering a what type question, you're probably best served by writing a brief description here and linking to the wikipedia.

We should put links to the wiki in relevant places in wikipedia. That is going to bring a huge number of users and potential editors to the site.

I hope i've not sounded negative. I really believe that Ubuntu is on the right track, and I wish I had more time to help.