On 11/16/18 4:43 AM, Cathy Crumbley wrote:

> So, how do we know how to be most helpful for users?

Basically, we don't.

Bugzilla tells us about what users expect to be able to do, but are
unable to do.

Surveys give us what users think that the documentation should cover (^6).

Analysing AskBot/web forum data tells what users want to do right now.

Analyzing Amazon book sales data tells what information people are
willing to pay for.
Analyzing TPB/Kat etc. data simply tells us what information people are
looking for, not necessarilly what they are willing to pay for.

None of that provides us with the information that people don't know
that they don't know.

By way of example, BAILS is implemented within LibO, (ignoring that part
of the functionality was eliminated in either 6.1.2 or 6.1.1). This is
great example of something that would be useful in maintaining
compliance with SOX, GDPR, and related legislation. Yet the absence of
documentation on how to use it, means that nobody asks questions about it.

A second example is the built-in version of LOGO --- LibreLogo. There
are two or three videos in English, and either one or two short papers,
describing a very basic program. There is a long paper in Hungarian,
which I don't read, and both Google Translate and Bing Translate mangled
beyond comprehension.(^1) What is needed here, is a document that
provides both the vocabulary and syntax recognised by LibreLogo.
Ideally, a rewrite of K&R, except for LibreLogo, rather than C.(^2)


I recently read a book on writing Agile Documentation.  The main thrust was:
* Create four or five user personas;
* Write documentation that covers each use-case for each of those personas;

Each persona has a different set of use-cases. By way of example:
* Molly, the receptionist, whose primary purpose is to look pretty.(^3)
 Figure out what she uses the product for, and write instructions just
for those tasks;
* Charlie, the programmer. Figure out what he uses the product for, and
writing instructions just for those tasks;
* Jake, the accountant. Figure out what he uses the product for, and
write instructions just for those tasks;

If having trouble figuring out what the individual would use the product
for, shadow them for a day or two, writing down when, and what they use
the product, or its functional equivalent, for.

As an example of use-case specific documentation, look at Thomas Quirk's
books on using Excel:
* Excel 2016 for Bilogical and Life Science Statistics;
* Excel 2016 for Business Statistics;
* Excel 2016 for Educational and Psychological Statistics;
* Excel 2016 for Engineering Statistics;
* Excel 2016 for Environmental Statistics;
* Excel 2016 for Human Resource Management Statistics;
* Excel 2016 for Marketing Statistics;
* Excel 2016 for Physical Science Statistics;
* Excel 2016 for Social Science Statistics;

The major difference between the books, is the scenarios used in
describing when, and how to use the specific Excel function.


Between built-in functions, included extensions, and third party
extensions, Calc has almost 2,500 functions.
I recently stumbled across a book _1,000 Built-in Functions of Excel_
It lists a function, the expected parameters of the function, and how
the function is used.

It seems to me that this is the type of documentation that would be
relatively easy for somebody who the time to write, and be very useful
to end-users seeking to close the "knowledge that we do not know that we
do not know" gap.  Distribute it as a book, not a set of pages on the
wiki. If they are currently described on the wiki, then transcribe to a
book format. If not on the wiki, then add each function to the wiki, as
it is being written for the book.(^5)


In updating _OOo in a Multi-lingual Environment_  for AOo, EO, and LibO.
I'm finding that things that could be done with OOo 1.1.3-ZA can't be
done with LibO 6.1.3. OTOH, some of the things I couldn't do with that
version of OOo, I can do with LibO 6.1.3. I'm documentating those
differences in a separate set of documents.

The bigger challenge I'm facing, is sticking with a 5,000 word limit for
each chapter. (^7)

One chapter is one language that uses one writing system, in one
country. For Turkish in Turkey, that means four chapters, one for each
writing system that has been used in the last 120 years. For Afrikaans
in South Africa, that means two chapters --- one for writing Afrikaans
using the Latin writing system, and one for writing Afrikaans using the
Arabic writing system.(^4)

I keep going back to
* Should I expect the reader to read the previous chapters;
* Assume the only chapter that will be looked at, is the chapter on the
country/language/writing system in question;

I'm writing for a niche audience, that probably will read the book,
before shunting it aside as a reference guide.  (Let's face it, how many
people can read English written in the Desseret Writing System today?
How many people even knew that Afrikaans was written in the Arabic
writing system.) On the flip side, it is the type of book that people
get, because the title looks intriguing.


^1: Both translate.bing and translate.google provided the equivalent of
converting "out of sight, out of mind" to "invisible, insane", in a
mammer reminiscent of toki pona's phrase for "ice coffee" --- "solid
water hot black bitter drink" .

^2: On second thoughts, I'm not sure I want to see a compiler written in
LibreLogo. On the gripping hand, that could make for a very useful
Easter Egg. On the fourth hand, K&R is probably the best written book on
any programming language one will ever encounter. It contains everything
one needs to write a good program in C, without leaving any aspect of
the language out.

^3: Most jobs, especially at the lower levels, have a primary function
that is radically different from the job description. WallMart's
greeters,for example, have a primary function of loss prevention.

^4: It doesn't help that Afrikaans uses glyphs from the Arabic Writing
System that aren't part of Unicode.

^5: As I am writing this response, my Internet connection went down.

^6: More than one company has done a multi-million dollar launch for a
product that multiple surveys, and focus groups said are highly
desirable, only to end up in a crash and burn scenario.

^7: In academia, a reference book is roughly 120 pages, or 10 chapters,
or 50,000 words long.  Thus, 5,000 words per chapter.


To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org
Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette
List archive: https://listarchives.libreoffice.org/global/documentation/
Privacy Policy: https://www.documentfoundation.org/privacy

Reply via email to