From owner-freebsd-doc Sun May 13 17:37:19 2001 Delivered-To: freebsd-doc@freebsd.org Received: from phoenix.welearn.com.au (unknown [139.130.44.81]) by hub.freebsd.org (Postfix) with ESMTP id 0BDA637B423; Sun, 13 May 2001 17:37:01 -0700 (PDT) (envelope-from sue@phoenix.welearn.com.au) Received: (from sue@localhost) by phoenix.welearn.com.au (8.11.1/8.11.1) id f4E0aN573048; Mon, 14 May 2001 10:36:23 +1000 (EST) (envelope-from sue) Date: Mon, 14 May 2001 10:36:23 +1000 From: Sue Blake To: Doug Young Cc: Rahul Siddharthan , Kathy Quinlan , N6REJ , freebsd-doc@FreeBSD.ORG Subject: Re: I'm leaving Message-ID: <20010514103623.B68348@welearn.com.au> Mail-Followup-To: Sue Blake , Doug Young , Rahul Siddharthan , Kathy Quinlan , N6REJ , freebsd-doc@FreeBSD.ORG References: <002b01c0db54$e0febaa0$5599ca3f@disappointment> <20010513171444.E26123@welearn.com.au> <00f401c0db7e$ff3ca2a0$fe00a8c0@kat.lan> <20010513122623.I97034@lpt.ens.fr> <20010514084709.A68348@welearn.com.au> <024b01c0dc05$b1314fc0$0300a8c0@oracle> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <024b01c0dc05$b1314fc0$0300a8c0@oracle>; from dougy@gargoyle.apana.org.au on Mon, May 14, 2001 at 09:37:35AM +1000 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org [Moved, it's a -doc issue now (was advocacy and newbies)] On Mon, May 14, 2001 at 09:37:35AM +1000, Doug Young wrote: > > And that is exactly the problem faced by many newbies: not knowing > > where to look, nor realising they're there when they've found it. > They > > can't tell because there are concepts that they don't have, and when > > they look at the documentation they might find vaguely familiar > words > > which are not used in every day speech and which have a particular > > meaning to people with a formal computer education. > > > :) ..... its called "martian" .... or maybe I'm confused & its really > "venusian" !!! I thought it was Klingon :-) Whatever it is, your MUA's line-wrapper seems to have come from the same place :-) I'll rewrap for you. > There is a limit to how much martian / venusian most of us can absorb > in a hurry. For many people its very limited, so since the official > folk didn't learn to speak the same language the majority of regular > folk do it appears that meaningful docs can only be written by a team > comprising someone with a reasonable grasp of english (or whatever > language), an expert or two in a consultancy role, plus an > interpreter who may not be an expert developer but speaks both the > developer language & english (or whatever) The problem we have is that the people with the skills to execute these good ideas, either don't contribute them to our docs (and we're left with a volunteer staff of hard working Klingons trying their very best), OR, they go off and do their own thing somewhere else, which is great to have but fails to enrich the FreeBSD docs in any way. Like so many things round here, we have lots of people ready to jump up with good ideas, even more people weeing themselves with excitement at the chance to code the infrastructure, but hardly a soul to do the actual work. This applies to FreeBSD doc ideas as much as it does to support ideas. "If you build it they will come" is a naive view does not work for support/docs, but it has been a popular pipe dream for the several years that I've been watching. Better docs/support requires supply of prose, not code. The first thing we need is people, working within the community, to do the stuff. You can sketch out a few docs and send them to freebsd-doc. I find SGML intimidating, but plain text is fine. If it's valid and useful, after feedback and editing and completion someone will step forward and mark it up and commit it for you. Anyone who doesn't want a precious word of their prose altered will have to do it some other way, of course. And there are other reasons why some people keep their docs sepaparte from the FreeBSD docs. But in general, we need people contributing to docs if there is going to ever be any improvement. And we need bums on seats and text on file, way way way before we need more should-be and should-be-nots and code. > > With these, once you've seen them in a unix context they're > > obvious, but they don't have instant meaning that leaps out for a > > beginner. > > > So why the commandment "Thou shalt never use visual representations" > (aka screenshots) ?? Hey maybe the docs folk are all visually > impaired & use one of those screenreader apps like "Jaws". Might > explain why all "official" docs muddle through with largely > unintelligible text rather than the 'picture tells a thousand words" > approach No, it's because nobody has submitted them for inclusion. That's how everything that's in the docs already has got there. If you have something worth adding, check on -doc that nobody's already working on the same thing, sound out your ideas, and send them to -doc for review. You could be surprised what makes it through that process simply due to the absence of any alternative. > Exactly .... maybe then we'd have official docs with words on the > pages rather than simply chapter headings & virtually blank pages !!! Exactly. > Where I started with this thread was trying to discover if its > reasonably feasable to write a step_by_step HOWTO about X-windows. Please, please do! And please do it as part of the FreeBSD Doc Project if you can. Then after it's done, you will become a role model who has found an omission and gone on to correct it, and others might follow. > > > > Exactly what are we expecting newcomers to know, and > > why can't we state those expectations clearly? > > > Thats a very good question & I'll be very interested to see the > responses :) Maybe some of the -doc people have thought about this. -- Regards, -*Sue*- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message