[FM Discuss] the reader the reader

[John & Melonie Curwood]

Hi Adam,

I haven't read the whole article yet but the excerpt from the article 
reinforces the Impressions I have got from pretty much all the Floss 
Manuals I've looked through, which is one of the factors that drew me to 
start contributing in the first place, they really have an end-user 
focus and don't assume too much knowledge from the reader.  I don't know 
if it is an intentional philosophy of Floss Manuals or just a by-product 
of community writing.  It may be the fact that so many educators are 
part of the FM community and this helps generate the drive towards 
respect for the reader.  I know that I certainly always have the end 
user in mind when writing and strive to make my writing reflect the 
sentiments expressed in the article.

Cheers,

John

adam hyde wrote:
> 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
>
>
>
>
>