documentation1Add my vote for this tag twiki_community1Add my vote for this tag usability1Add my vote for this tag create new tag
, view all tags

The Documentation Focus Group

The Documentation Focus Group is tasked to enhance the usability of the TWiki.org website with customer focus in mind.

Focus group members:

Doc work focus:

Related topics:

-- Contributors: MeredithLesly, ArthurClemens, PeterThoeny


It's too bad that little or nothing is being done to help our various users. A lack of adequate documentation or poorly written documentation should be considered a bug, in my opinion.

Clearly we need a top-level navigation scheme. (At least I think that's clear). But waiting until a scheme is worked out leaves people going to #twiki and Support, both of which wind up consuming a lot of developers' time.

(I should note that choosing the Comment plugin was because of its usefulness and ease-of-use, not the quality of its documentation.)

-- MeredithLesly - 02 May 2006

If documentation is poor it is perhaps because it isn't been found, and not being found it isn't used, and not being used it isn't refactored.

I think the biggest problem is the navigation, not the quality of the documentation. If you fix the former the latter will also be fixed; there should be a virtuous cycle of document use and improvement for as long as we maintain good navigation.

My recollection/assumption from the meeting was the the focus of this group was to be the navigation to the documentation (CustomerFocusedTWikiOrg), not the documentation itself. We need a group to create a good navigation scheme but everyone will be able to create documentation once it's done.

And there's nothing stopping you creating documentation now. You just won't have the navigation scheme to place it in yet. It might even aid creating the navigation to see the kinds of documentation it needs to provide navigation to.

-- SamHasler - 02 May 2006

Peter has clarified what he want to accomplish with "tagging" in t.o. That is, he considers it a way of classifying topics. This makes a lot of sense to me, as a popup menu is easier to use, does not change the modification date or last author, and does not enforce a single classifcation the way TopicClassification does. TagMePlugin/TagMeCloud enable a much broader use with, as he's noted, willy-nilly creation of tags and the maintenance thereof.

Therefore I suggest:

  • creating a new plugin, ClassifyMePlugin, so as not to lose the more free-form TagMePlugin functionality, which I'm sure people will find useful in other places, as well as hopefully supporting an easy-to-use way to manage the results
  • discussing a set of classifications broader than those in TopicClassification but not so large that choosing among them seems overwhelming.

Whether we also keep TagMePlugin installed is a non-documentation-related question to also be considered. If people are using it for personal tagging, then it seems that is serves a purpose, albeit a different one, as well. Overloading one plugin for two quite different functionalities doesn't seem to be in anyone's best interest.

-- MeredithLesly - 04 May 2006

Tagging has been here for a while now and my personal view is like I feared from the start. The tag cloud just becomes a cloud. The number of topic you get when you click on a tag link is getting larger and larger and more and more useless. Tags overlap. Tagging is near random and very individual. Tagging is a poor excuse for not doing proper navigation structure. Tagging can have two good effects. It can limit the search hits and it can put the topics with most votes at the top of a search. So it can be an improvement of searching. And the second is as a personal book marking tool. Until you have tagged so many topics that it becomes as useless as ones bookmarks in the browser.

The focus group work should focus on navigation. When you arrive at twiki.org there should be a clear path from top index to lower indexes until you arrive exactly at a list of very few topics that describes what you need.

And good navigation starts with mutually exclusive choices so that it becomes near impossible to choose the wrong path.

-- KennethLavrsen - 06 May 2006

I agree that the most important step now is to create content navigation: clear link labels (and not rely on WikiWords only: see AvoidClickHereLinks about long link labels; TopicDisplayName if implemented could also help in that). Topics should create a scent of information and that can be achieved by having more (not less) links on the page, grouped by subject.

Note that the first default page the TWiki users sees, Main.WebHome, is already unclear in what belongs to what: the grouping "Main Web Utilities" lists TWiki topics as well. We need to look critically at every page.

-- ArthurClemens - 06 May 2006

Kenneth, that's why I was suggesting using a variation of TagMePlugin called ClassifyMePlugin which wouldn't allow the adding of new tags via the tagging mechanism. The problem with that is that I don't see how we could come up with an effective and efficient (i.e., not overwhelming large) set of tags.

I agree with you that tagging, even if we came up with a good set of tags, is not a substitute for a good navigation structure. But thinking about a classification tag set might possibly help us figure out what the navigation paths would be.

All this being said, even coming up with a navigation structure that you described seems overwhelmingly difficult, given the number of topics. I hope I'm wrong, but the amount of time involved in looking "critically" at every page seems monumental.

-- MeredithLesly - 06 May 2006

Glad someone is starting to do something on this, at long last! But don't get caught up in analysis paralysis just yet; you don't have a clear set of requirements to analyse!

Here's my poor effort. There are two types of user we are trying to help:

  1. Users
    1. Users trying to find out how to do something need a focused, easily searchable resource (a knowledge base).
    2. The KB content must be independent of any single TWiki release version
    3. The KB has to be aggressively managed. It must not become a dumping ground for brain dumps and newbie piffle,
    4. It must be easy to manage (note that indexes are in general hard to manage, Searches are much easier).
    5. It shouldn't try and guess what a user is going to search for (categories are less useful than a general purpose search)
    6. But KB articles should have keyword (or tags, or whatever you want to call them).
    7. KB articles should be indexable by google.
    8. By default, a search of KB pages should only show KB pages.
    9. The KB should pull together existing KB topics from Codev, Support, and possibly TWiki as well (e.g. cookbooks).
    10. It should be easy to enter new KB articles, e.g.
      1. Goto the "new KB article" page.
      2. Type in a set of keywords (page shows summaries for all KB articles with those keywords, to make sure you are not overlapping)
      3. Create the new page with those keywords.
    11. KB pages should encourage statement over discussion. Would be good if articles could be annotated by sticky note.
  2. Developers need 2 things:
    1. A whiteboard space
      1. A very simple classification scheme, with 3 or 4 topic categories, is enough. Classifications need to be general, because it will be rare that a topic fits exactly.
      2. Maintenance tools (such as simple "by age" pages) would be good, but are not essential.
      3. Just because a developer types something, that doesn't make it true. Developer whiteboard pages must be kept separate from the KB.
      4. Developer pages are all about brainstorming and discourse.
      5. Most developer pages are in Codev, though some are probably in Plugins.
    2. A developer documentation resource
      1. A place for factual pages about how TWiki development is done (processes etc)
      2. Some pages are in Codev, some in Plugins

Note that I am not presupposing any solution, just stating requirements.

-- CrawfordCurrie - 06 May 2006

After some consideration, I think that someone should take my place in this group. Given my several attempts to try to get better documentation and structure, it made sense for me to be nominated for it. But most of these attempts were made before I was sufficiently familiar with TWiki code and Perl to be able to contribute in any other way. Given that I'm now able to contribute to the coding efforts, that feels like a better use of my time. In addition, the style of working on the code suits me far better than what's apparently desired for working on documentation. (Why it involves so much more process and planning to write and organise TWiki documentation than to write code baffles me, but that's the reality.)

It doesn't mean that I'm no longer interested in TWiki having easier-to-find and easier-to-use documentation. But, unlike at least 2 of the original members of the group, I don't have the patience to discuss how to do things for weeks or months. Therefore it makes sense for the group to include people whose temperament is more suited to extended planning and whose time can most productively be used in this rather than other areas.

-- MeredithLesly - 07 May 2006

Should this topic be renamed to NavigationFocusGroup?

There's an Eye tracking heat maps study that this group may find useful/interesting.

-- SamHasler - 11 May 2006

That presumes that all that's involved in fixing the doc is navigation. See WebsAreUseful for why that is not necessarily the case.

As to an early point of yours, dropping more topics into the existing disorganised and overcrowded webs doesn't make sense to me. Had we been allowed to use a non-public web to copy, edit, and organise topics, I (and hopefully others) would have worked on extracting useful information that's scattered everywhere and we might at least have a sketch of something that works by now. In fact, I spent some time doing just that when a web was created accidentally (after making it non-public, of course), but Peter chose to lock it down, leaving the time I spent on it wasted. There's only so many times one can be rebuffed before it taking the heart out of one, and that time for me is long past.

-- MeredithLesly - 11 May 2006

A link that may be interesting:


-- RafaelAlvarez - 13 May 2006

As was discussed in #twiki today, what documentation is important depends on both on how people are using TWiki and how we hope people will use TWiki. If all key developers and core group members want for TWiki is, in essence, for it to be little more than a way for developers to create applications with some wikiness in it, with ordinary users doing little more than filling out forms and/or creating barebones topics with little formatting and no smarts, then both coding and documentation efforts should be aimed with that goal in mind. There's no need for a doc web if 99% of the users need nothing more than one page on how to do simple formatting.

I seem to have had a very wrong idea of what TWiki was about. I wanted to leverage of of some of the plugins -- ironcially, the key one of which turned out not to work in Dakar -- but I always intended ordinary users to do more than what I've described above: at the very least simple things like putting a %COMMENT% in their topics to elicit feedback.

If 95% of the documentation isn't intended to be read by most people, then I guess the quality and the ability to find the documentation doesn't matter very much. At least that will make the goals of this group a lot easier to accomplish, except for the problem of getting that 95% (or whatever the number actually is) out of the way.

-- MeredithLesly - 14 May 2006

Direct IRC link to discussion mentioned by Meredith: http://koala.ilog.fr/twikiirc/bin/irclogger_log/twiki?date=2006-05-13,Sat&sel=409#l405 (22:00-24:00).

The requirements as summed by CDot looks very precise and ambitious imho.

-- SteffenPoulsen - 14 May 2006

CDot's instructions are precise except for how he starts out: "Users trying to find out how to do something". What kinds of users? What kind of "something"?

He also leaves out two important issues: users, of whatever variety, need to know they can do something; and they need to know enough to know what the right question is.

(I'm not criticising CDot for this, merely pointing out that his precision only goes so far, as I'm sure he would agree.)

-- MeredithLesly - 14 May 2006

I've copied the current version of the CommentPlugin documentation that I'm providing to my users to CommentPluginDoc as an example of what I consider user-friendly documentation. (It's not finished, so I'm sure it could be made even clearer and more user-friendly.) There is a second, linked page that includes the various customisation features which I have not included.

I've put this page up so that folks can compare what I consider user-friendly to what is currently offered to our users. And, to make an essential point for the umpteenth time, navigation or topic tagging or classification may help them get to a destination more easily, but if the destination doesn't contain the right content, what difference does it make?

-- MeredithLesly - 14 May 2006

Edit | Attach | Watch | Print version | History: r24 < r23 < r22 < r21 < r20 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r24 - 2006-07-18 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.