[FM Discuss] the reader the reader

[adam hyde]

hi,

I just wanted to outline some comments in the review from Linux Pro
Magazine that I found really interesting as they also reflect what Bob
Stein (Future of the Book Institute) said about FLOSS Manuals material.
Its interesting as it seems others have picked this up also - I think
Biella referred to it in the FM wintercamp video
http://blip.tv/file/1879311

It has to do with the respect that many of the manuals have for the
reader. it strikes me that this is not coincidental, and even tho we
certainly hurd cats when writing material via book sprints, many of the
manuals contain this respect within the lines of txt...i think this is a
product of community writing, but it is also part of the attitude we
seem to be fostering within FM...below is the excerpt from the review,
i'd be really interested in anyones thoughts on this...

------
http://www.linuxpromagazine.com/online/blogs/off_the_beat_bruce_byfield_s_blog/review_floss_manuals_introduction_to_the_command_line?blogbox


<snip>
The first thing I noticed about the book was its readability. Unlike
many books about technical subject, this one is not written in the
academic dialect, but some one that approaches spoken English. Sentences
of under a dozen words are common. The tone tends to be casual without
much of the wordiness that usually creeps in when efforts at casualness
are made.

Just as importantly, the contributors seem to be keeping the audience --
presumably, those new to the command line -- in mind, another challenge
that defeats most writers on technical subjects. Too often, writers
forget that their readers lack their expertise, and lack any sense of
what needs to be explained. By contrast, Introduction to the Command
Line is explicit about what it is doing. For example, the opening pages
define a command as "a file that can be executed," and describe white
space as "blanks and tabs -- things that show up white on paper." With
the same clarity, directories are described as "containers of files."

Along with this clarity comes a refreshing frankness. The introduction
assumes, probably correctly, that its readers will usually be opening a
command line, saying bluntly that only system administrators are likely
to otherwise these days. Then, after proceeding to explain how to open a
virtual terminal in Ubuntu (probably not the FSF's preferred
distribution to use as a reference point, but perhaps justified on the
grounds of popularity), the introduction admits that the terminal
doesn't give you much help at first glance. "You're expected to know
what to do -- and well show you," the introduction explains. 

Similarly, when talking about the output of ls from the root directory,
the manual is careful to say, "You may see some files or directories in
your root directory not discussed here. For now you only need to be
concerned with one directory: your home directory. . . . Most of the
time you don't need to know about the directory structure outside your
home directory, but this knowledge occasionally comes in handy." What
readers might wonder about is almost always carefully anticipated and
voiced, and what the manual expects of readers is, as well.

</snip>



adam




-- 
Adam Hyde
Founder FLOSS Manuals
German mobile : + 49 15 2230 54563
Email : adam at flossmanuals.net
irc: irc.freenode.net #flossmanuals

"Free manuals for free software"
http://www.flossmanuals.net/about