List of technical documentation: is it a useful page? What should be here? What should not?

Michael Shiloh michael at
Thu Aug 28 00:23:38 CEST 2008

Minh Ha Duong wrote:
>> In brief: I agree with removing manually maintained out-of-sync article
>> list pages, but we should try harder with category intros then. :-)
>   Having multiple sources of information is GOOD. Big advantages of lists 
> include:
> 1. They can be formatted nicely, see the "Community application" page
> 2. They can be more than up to date, and actually provide a way to point out 
> _desired_ pages missing from the wiki
> 3. Some users prefer browsing or searching categories, some users prefer lists 
> pages.

I think more troubling than the fact that there are multiple sources, is 
the fact that neither is automatic. (The category list is automatic, but 
requires manual assignment of category on the page.)

Thus both these lists are only as good as we maintain them, and in spite 
of how well-intentioned we are, having two lists to maintain is more 
time consuming than one list.

But the real problem here is the user perspective. Remember the thread 
that lead to the creation of the wiki maintainer volunteers and this 
mailing list. It was due to the sorry state of our wiki, and I'm afraid 
that even if the list is nicely formatted, and even if a user prefers a 
list to a category, if the content is out of date, wrong, or lacking, it 
is worse than useless. It turns people off.

So I claim that in spite of the possible advantages of multiple sources, 
we stand a better chance of improving the sorry state of the wiki if we 
have fewer sources.

I claim that every time you delete a useless, redundant, confusing, or 
misleading page you improve the sorry state of the wiki. And that is why 
we are here.

>   So let's try to understand once again what Brenda really wanted this page to 
> be about. 

I guess I still don't understand this.

More information about the documentation mailing list