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