[FM Discuss] some thoughts on friendly manuals

[Janet Swisher]

Hi all,

It was great to see Adam at the Mozilla Summit. I believe the event is
"bi-annual", in that this is the second time they've done it, and the
first one was in 2008. I haven't heard anyone mention Summits earlier
than that.

I was bummed that none of Adam's talk proposals made the final
program. There were a ton of proposals, and not nearly enough time for
all of them. Everyone left with brains overflowing as it was.
Fortunately, Adam did get to demo booki to a few key people
informally.

On Fri, Jul 16, 2010 at 5:50 AM, adam hyde <adam at flossmanuals.net> wrote:
> hi,
>
> i went to the mozilla community meeting in Whistler, Canada last
> week...I will send a report event shortly...

> what i wanted to mention quickly is that one of the new heads of the doc
> team (I forgot his name but i will remedy this in the report) mentioned
> that he found "making the docs friendly" increased the effectiveness of
> the docs. Now moz being what is has such a huge amount of online traffic
> that they can measure the increased traffic when they change the color
> of links and then gauge the effectiveness because the smallest changes
> become statistically significant. The demo he gave was when they changed
> a small part of a doc from a very formal style (the SUMO support pages
> are very formal) to an informal chatty style they had an incredible
> increase of traffic. well, stats are stats of course, and i dont know
> what measures they were using (time spent on a page, number of hits?
> etc) but i believe this evidence as it is also what i have always
> personally believed about docs (you only hear what you want to
> heh!)...maybe janet can add something to this as he knows the chap and
> was also at the same presentation/discussion

That was Michael Verdi, who is the new Content Manager for the Support
Knowledgebase, which contains the end-user documentation for Firefox.
The test that he did involved rewriting a topic to convey not only
*what* you can do with a feature, but *why* you might want to use that
feature. That resulted in a 13% increase the number of people who
clicked "Yes" for "Was this article helpful?" at the bottom of the
page. Given the number of people who view that page, that translates
to something like 800,000 more people per year being helped by the
page.

There was a long discussion after his talk, with a lot of the
participation coming from translators. One point was that an informal
tone may not translate cross-culturally. For example, in a language
that has formal and informal pronouns, it might not be acceptable to
use an informal pronoun in documentation (depending on the culture).
But giving an example of why the user might need the feature seems
pretty universally helpful.

> it made me think of fm (many of our docs are friendly) and this project:
> http://diveintohtml5.org/
>
> and then i thought also about the above example (html5) and how it uses
> public domain images AND that fm is working with archive.org to
> implement booki for proofing OCR scanned materials...which lead me back
> to thinking..why dont we use some of the images from public domain books
> in our manuals? could be interesting to start talking about this and
> trying a few things out....

Speaking of public domain materials, I just came across this: PS
Magazine, a US Army publication on preventative maintenance, which
featured artwork from some of the great comic-book artists of the 50s
and 60s, is now available online, and because it was a US government
pub, it is public domain.
http://dig.library.vcu.edu/cdm4/index_psm.php?CISOROOT=/psm

--Janet