Date: Wed, 7 Apr 1999 11:18:09 +1000 From: Sue Blake <sue@welearn.com.au> To: Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: Sean Kelly <kelly@plutotech.com>, doc@FreeBSD.ORG Subject: Quick guides [was: Organisation change for the Handbook] Message-ID: <19990407111809.59510@welearn.com.au> In-Reply-To: <19990406191159.D6083@catkin.nothing-going-on.org>; from Nik Clayton on Tue, Apr 06, 1999 at 07:11:59PM %2B0100 References: <19990405234615.B6083@catkin.nothing-going-on.org> <370A3434.26DB3045@plutotech.com> <19990406191159.D6083@catkin.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Apr 06, 1999 at 07:11:59PM +0100, Nik Clayton wrote:
> On Tue, Apr 06, 1999 at 10:20:04AM -0600, Sean Kelly wrote:
>
> > I mostly agree. In particular, kernel configuration is one of out
> > better chapters in the current handbook.
Yep, it was the first thing I had to do after installing. It took days
and required a lot of other learning (unix, editing, ...) along the
way, but the kernel came together in the end just like it said.
> > Yet some amount of kernel
> > configuration appears in nearly all the other chapters: in networking on
> > setting up the kernel with an Ethernet controller; in printing on
> > setting up the kernel for parallel ports; etc.
>
> Yep. One of the things each book will need is a "_topic_ for the
> impatient". This is just bullet points that provide the minimal
> information for those that know what they're doing, and don't need
> handholding.
This is also something that is very important for those who know
little. You don't help a raw beginner by dumping everything you know
about a topic, no matter how much they might need to understand all
that stuff eventually. If they can't stand back and see it as a doable
whole, visually follow a path of few steps and see what they're working
towards, it becomes too much to take in. Take this for example:
> For Kernel Configuration this would be something like;
>
> * Make sure you've installed the kernel sources.
>
> * Copy /sys/i386/conf/GENERIC /sys/i386/conf/KERNELNAME, where
> KERNELNAME is the name you want for your new kernel.
>
> * Read the comments in GENERIC and LINT (in the same directory) to
> determine which entries you need to add and remove.
>
> * # config -r KERNELNAME
>
> * # cd ../../compile/KERNELNAME
> # make clean depend
> # make all install
>
> * # shutdown -r now
A lot of new people with no experience will need to have something like
the above to guide their reading of the full detail, or else they'll be
overawed and give up. If I look at that and don't understand any of the
steps, at least I can get some idea of what kind of steps they are and
how many parts I'll have to absorb before I get to the end. It is
necessary at the outset to be able to see the task as a whole.
Most people's brains can hold approximately seven pieces of information
together at one time. Familiar information groups itself so that one
can hold seven of these groups (or concepts), or seven tiny new pieces,
or a mixture. What we regard as one item might be ten or twenty to a
newcomer. We're writing instructions (docs) for hardware (brains) of a
type that we don't have access to any more.
For example, someone who knows absolutely nothing might temporarily
register the list above in their mind as:
1. Make sure that something with that funny name is installed.
2. Decide on a name for my kernel and copy some file that I've
never heard of to that new name (I think).
3. There's some task to do with adding and removing some things, and
there will be two files to read to help with these decisions.
4. Type a whole lot of unknown commands, probably need to be root.
5. Shut down the computer.
That's about as long as it can afford to be. Despite its look, this
rough list is enough to give a reference pathway through the ensuing
study, even though the original list didn't make a lot of sense. One of
those steps might take hours or days, especially if they need to detour
midway to learn more unix commands, look up hardware manuals, or to
experiment or ask questions when the documentation doesn't make sense.
Without having some concise overview of the steps it is very easy to
get lost or disheartened.
Contrast this with the typical many pages of carefully written text
which describe the finished outcome, start with background info,
deliver basic skills, specific skills, each task broken up into its
learnable subtasks, a multitude of little steps which are all easy but
far too many to see how they fit together in relation to the overall
goal. Plugging them together as you go is not enough on its own. That's
why build-it-yourself hobby kits come with a photo on the front of the
box and an exploded view on the back and deliver the tweezer-sized
pieces with instructions after breaking the shrinkwrap. Advanced people
don't need the bottom-up approach, people approaching something totally
new need to see it in *both* directions.
I have yet to find anything to do with FreeBSD that is not very easy to
do. It's just that there's always so many of these easy things to do!
It's not enough for novices to learn all the little steps. Unless they
can join those steps together into chunks of increasing size up to a
whole task, it'll always seem a lot harder than it is, no matter how
much explanation we pump into them. The two devices most useful here
are repeated real practice at appropriate stages, and having a concise
overview of the steps for reference from the outset.
If you're preparing documentation at different levels, please don't
write off the quick guide approach as only useful to those in the know.
For many learners it can make the difference between giving up and
giving it a go, even if they don't understand the items initialy.
--
Regards,
-*Sue*-
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990407111809.59510>