[FM Discuss] the reader the reader

[Edward Cherlin]

On Mon, Mar 30, 2009 at 7:10 AM, adam hyde <adam at flossmanuals.net> 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

This is one of the best-written and best-thought-out reviews I have
ever read. I hope somebody is collecting these links for a page on the
Web site. Actually, one review page per book.

> 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...

A lot of it seems to be the fearlessness you require of us, to go in
and finish or fix other people's work without checking every change
with them, enabled by the ability to roll back changes. I just wish I
had carried through a bit more and taken out the Willie Sutton line. I
think it was because I was working on something else when I saw it,
and forgot to go back. I have an idea how to help myself keep track of
such things.

> ------
> 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.

Clearly in part because non-techy editors have complete permission to
fix the work of us more technical writers.

> 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.

I think this last sentence is broken. Can you tell what it means?

> 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>

Let's look at the negatives.

1) too much cleverness: Willie Sutton. I agree.

2) Continuity. I agree.

3) Section on scripting too short? It was supposed to be short. Just
gives a few tricks? Doesn't explain how the languages work? True, but
what can we do, short of a separate book? Maybe we needed to call it A
Tip-of-the-Tongue Taste of Scripting, talk about how little we're
showing, and give more links to follow up.

I would say that we executed what was planned quite well, but that we
failed to plan some things.

o Somebody needs to take charge of continuity editing.

o We may need to be more systematic about editing and proofing. Did
everybody who did that start at the beginning and fail to make it
through to the end? At the Circumvention sprint, Adam made a table
where we could check off what we had done.

o A little more advance discussion on topics would be helpful, or else
a session at the very beginning where we try to bring everybody in,
and in which we discuss the plan and the outline, and we do not write
content.

o The Firefox and CLI sprints were officially two days. I think we need three.

> 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
>
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>



-- 
Silent Thunder (默雷/धर्ममेघशब्दगर्ज/دھرممیگھشبدگر ج) is my name
And Children are my nation.
The Cosmos is my dwelling place, The Truth my destination.
http://earthtreasury.net/ (Edward Mokurai Cherlin)