Proposed Interim Documentation Guidelines

These come from EdinburghReleaseMeeting2006x05x15

1. New supplemental documents will be raised in TWiki web
2. Update existing docs in TWiki, Codev, Support web as usual, and...
3. Link to doc topics from appropriate SupplementalDocument topics and from core docs
4. Tag content

-- Contributors: PeterThoeny

Discussion

IMO, this was insufficiently discussed to be guidelines, even interim ones. So, a few starting points:

• Creating new supplemental documents leads to the usual SearchedURIsCantChange problems that are already contraining reorganisation. I am loathe, therefore, to create new documents. (Well, except in Codev, because here there be so many dragons that a few more fiery beast don't really matter.) It also begs the question of what a supplemental document is. Is every document that's not offical by definition supplemental? What makes something "official" anyway?

• Without policies regarding concerns about proposals, opinions, and the like making their way into TWiki and Plugin documentation, it makes editing content potentially contentious. See edits in Plugins.ReadmeFirst for an example of this.

• Tagging content for the purposes of navigation is currently too ill-defined and needs resolution of various issues raised in TagMeDiscussions starting in May.

-- MeredithLesly - 16 May 2006

TWiki.SupplementalDocument says: documentation not included in the latest release. But if people do not find an answer in their local installation (and perhaps finally) come to twiki.org to find more, will they just be searching in Supplemental Docs? I think they do not care it is supplemental or not, as long as they can find an answer.

• The supplemental documents are not isolated documents. There are linked from the official TWiki documentation entry point on TWiki.org; and there are many links from the distribution documents to specific supplemental documents. Think navigation and create links accordingly. -- PeterThoeny - 18 May 2006
  • We can't "think navigation" unless we've got the right topic open already or try to find what the right topic is. Assuming there is a right topic. Good navigation is necessary. It's not sufficient. -- MeredithLesly - 18 May 2006

So if we define guidelines here, I would like to see them for all documentation.

From SupplementalDocument, many existing documents in the Codev, Plugins and Support webs contain useful supplemental information. Rather than recreating the content in the TWiki web, it is better to reference them from one of the existing supplemental documents in the TWiki web. - except that the referenced information needs to be structured already.

While restructuring/rewriting, we could help ourselves by marking topics (or topic sections) as "Needs rewrite to include in MyTopic", "Contains answer to MyQuestionTopic" and so on.

-- ArthurClemens - 16 May 2006

"Recreating the content in the TWiki web" is not the only alternative, unless one insists on leaving everything where it is and not allowing any new webs. Gathering the relevant documents in one place in another.

And, yes, there's a serious chicken-and-egg problem.

-- MeredithLesly - 16 May 2006

I asked a couple of TWiki users what search tools they use to find answers; not specifically on TWiki, on anything. They of course said "google". Then I asked specifically about TWiki; they said "google". The blithe assertion that CoolURIsDontChange assumes that people bookmark resources, and the blither assertion that SearchedURIsCantChange seems to assume that the search engines never refresh their databases. But a typical grunt searching for help doesn't have, and doesn't keep, bookmarks; they use the familiar search resource that finds new stuff as well as old. Google. If people use google each time they search for answers, then who cares if the URIs change? Anyone who searches on google for support knows that it is far more useful to find a single authoritative reference, than to hit multiple unmaintained resources.

Now, I'm not averse to allowing docs to exist where they are. But consider the maintenance problem. How does a maintainer know which of the three versions of the same advice to keep up to date? Where does someone who has just struggled through a problem add a FAQ?

So, when considering how to help people find support, maybe we need a slightly more radical view:

1. Indexes / tags are a waste of time w.r.t people looking for support
2. TWiki search is pretty much useless, because the scope is so limited. Disable it in the Support web. Point people at Google instead.
3. Want to make sure an FAQ is answered correctly? Make sure google hits the right resources in TWiki.org, and aggressively prune misleading resources.
4. It's too hard to move docs, so give up trying. Who cares where the docs are; as long as Google indexes the right ones?

-- CrawfordCurrie - 17 May 2006

How can we make sure Google returns the right resources? Perhaps by adding a few keywords based on the topic classification?

How often are Google indexes updated?

-- ArthurClemens - 17 May 2006

FWIW, I frequently use Google for search and click on the "cache" link because of speed, and because I learned that many times I won't find what I am looking for if I click on the direct link (because of link rot or content change).

-- PeterThoeny - 18 May 2006

TWiki search is also useless because of the number of hits. In Codev, at least.

And I hit cache iff the link doesn't work. I don't want old data unless there's no new data.

-- MeredithLesly - 18 May 2006

TWiki search in a large web is useless because there is no search ranking. If we add ranking based on backlinks, age and tag vote we have a better search.

-- PeterThoeny - 01 Jun 2006