On Tue, Nov 13, 2012 at 5:05 PM, RGB ES <rgb.m...@gmail.com> wrote:
> 2012/11/12 Rob Weir <robw...@apache.org>
>
>> On Sun, Nov 11, 2012 at 9:07 PM, RGB ES <rgb.m...@gmail.com> wrote:
>> > 2012/9/20 RGB ES <rgb.m...@gmail.com>
>> >
>> >> 2012/9/16 Keith N. McKenna <keith.mcke...@comcast.net>
>> >>
>> >>> Greetings All;
>> >>>
>> >>>
>> >>> In order to stimulate some discussion on user documentation I have
>> added
>> >>> the hollowing page to the User Documentation Plan on the Plannig Wiki:
>> >>>
>> https://cwiki.apache.org/confluence/display/OOOUSERS/User+Guides+Revisted.
>> >>> It offers 3 scenarios or the creation of the docs. I believe that we
>> can no
>> >>> longer put this issue aside.
>> >>>
>> >>
>> >> I added a child page were I think aloud about scenario 3 and start the
>> >> discussion about how to organize the documentation if we decide to build
>> >> our own
>> >>
>> >>
>> https://cwiki.apache.org/confluence/display/OOOUSERS/Details+on+Scenario+3
>> >>
>> >> Regards
>> >> Ricardo
>> >>
>> >
>> >
>> > Since some weeks there is an ongoing effort on the ES wiki to organize
>> the
>> > basic documentation for AOO.(1) I experimented with the distribution of
>> > different arguments and arrived to a configuration that I find
>> interesting.
>> > This distribution is different from usual user documentation in the sense
>> > that it is highly cross referenced: The first chapter try to give a
>> general
>> > description of AOO as a whole, without entering on the details of each
>> > specific app while the following chapters reference to the first one as
>> > much as possible. After that, each chapter clearly separate direct
>> > formatting from styles but trying to not explain same things twice:
>> > configuring a numbered list indent is the same when doing direct
>> formatting
>> > or modifying a list style, so... more cross referencing.
>> >
>> > Based on this (not completed yet) experience I added a "proposed TOC" to
>> > the "Details on Scenario 3" page. Only chapters 1 and 2 are really
>> > detailed, but the idea is to give to the Calc, Impress and Draw chapters
>> a
>> > structure similar to the one used on Writer's chapter.
>> >
>>
>> I like how you break it down.   It is similar to how DITA looks at
>> technical documentation as being modular, with three main kinds of
>> topics:   concept, reference and task.
>>
>> Reference would be like the detailed menu by menu item descriptions
>>
>> Concept would be explaining what a style is and why it is important.
>>
>> Tasks would be very direct, "How do I..." instructions.
>>
>> A very busy person might consult a task directly, to learn how to do
>> something.  Maybe it has a link to a concept page to provide a higher
>> level view, if they want it.  Or they could just follow the tasks
>> instructions and "get it done" without understanding the details.
>> That's fine.
>>
>> Now I must admit that IBM has never won a Nobel Prize in Literature
>> for our product manuals.  But what we have learned is that there is
>> value in focusing on the user's tasks -- what they want to do -- from
>> their perspective, and not focus on the product.
>>
>
> I agree as a general concept, but I think the possible uses of AOO are so
> broad that it is quite difficult to identify definite tasks. For example,
> writing a letter seems a quite different task from writing a book, but once
> you learn how to use styles both tasks imply exactly the same actions from
> the user: the only real change is in the "numbers" (more styles used, more
> pages, more objects) but the "what do you need to do" is almost the same.
> So if we write a task explaining how to write a letter, maybe a new user
> that needs to write a thesis will skip that chapter, thinking it will not
> help him/her because "it's too basic" while a task explaining how to write
> a thesis will scare someone who just need to write a letter.
>

Well, I think we need the user to meet us half-way.  I wouldn't have a
task on "writing a letter".  As you say, this is very broad.   But
having a comprehensive chapter on lists in all its gory detail might
be too broad as well.  It is purely conceptual and is the long way to
a user with an immediate question .

In the middle might be:

-- How to number a list starting at something other than 1

-- How to continue a list

-- How to control bullet styles for nested lists.

So my view of a "task" is much smaller.

In any case, this is not an either/or.  It is good to have the
reference and conceptual material as well.  But easy-to-follow tasks
(or think of them as "cookbook recipes") can help as well.


> On the other hand, maintaining the focus on the firsts chapters we can add
> some "sample tasks" on the last part: "Integrating components". For
> example, a more or less detailed guide explaining how to write a report
> were you need to insert Charts from Calc, drawings from Draw, database
> info, multimedia files and so on, but always linking to the first chapters
> when details are needed.
>
> Regards
> Ricardo
>
>
>
>>
>> A little chapter on this idea here;
>> http://www.ibmpressbooks.com/articles/article.asp?p=327993
>>
>> But I think we can do a mix, since moving from basic tasks to being a
>> proficient user requires that the user eventually *understand* how the
>> product works, not just follow steps in a book.  So eventually they
>> want concepts.  But at first, they are probably more task-oriented.
>>
>> -Rob
>>
>>
>> > Regards
>> > Ricardo
>> >
>> > (1) http://wiki.openoffice.org/wiki/ES/Manuales/GuiaAOO
>>

Reply via email to