Words to avoid?

[Dan McGarry]

Matthew Paul Thomas wrote:
> 
> That's certainly true, but that leaves open the issue of where to teach 
> those things. Help is apparently used mostly by experts to begin with. 

This seems to subvert the contention that documentation needs to be made 
more accessible. I thought the purpose of this exercise was to reduce 
people's reliance on experts and specialised knowledge.

> <http://blogs.msdn.com/jensenh/archive/2005/11/29/497861.aspx> And if 
> the help pages on how to change your screensaver, how to share your 
> music collection, how to configure Ethernet connections, and so on, all 
> included explanations of how to use checkboxes and scrollbars and so on, 
> that would get pretty tiring pretty quickly. 

With respect, you're anticipating a poor implementation, which is not at 
all a necessary outcome. There are a number of visual means which can be 
used to convey the context in an intuitive way, none of which require 
elaborate and potentially irrelevant explanation.

> (That's what I meant by "we 
> can assume people know how to use checkboxes" -- we can assume they know 
> it by the time they get to the help for some other topic.)

In my last post, I gave one small example of a wider issue: That 
intelligent people sometimes be confused by things that others take for 
granted.

I'm not simply suggesting that 'people in the developing world won't get 
what checkboxes are for' - though this does happen frequently. I'm 
advising that we'd be better off not making too many assumptions about 
the audience. IMO, we'll all be much better served by focusing on a 
simple, consistent and unambiguous lexicon and style guide.

For many people, technical terms derive all of their meaning from the 
context. I wouldn't be terribly upset calling a checkbox a 'frobnitz', 
provided that it's done consistently and its meaning is clear. 8^)

In my experience, it's important to focus on clarity first, simplicity 
second and brevity last.

That seems to be the direction of much of the discussion on this thread 
already; in fact, I was only attempting to suggest that we not lose 
track of that.

> A better way to teach things like that, though it probably won't be 
> developed by anyone unless they're paid to do it (a Summer of Code 
> project, perhaps?), would be an "Ubuntu Basics" interactive tutorial -- 
> a program that coaches you in how to use a mouse (including common 
> graphical controls), how to use windows, how to use the file manager, 
> how to edit text, and so on.

There's always a place for this kind of thing. I agree that there's a 
great deal of wisdom in suggesting that everyone, er, read the fine 
manual before starting in on something new. I also agree that we should 
create as fine a manual as possible for this purpose.

But the fact remains that people are very task oriented when they use 
support services, so there is a need for documentation that does not 
make too many assumptions about its audience.

Otherwise, we could just stick with the man pages we already have. 8^)

Regards,

-- 
Dan McGarry	it.psl at fsp.org.vu

IT Consultant
Community Communications Project