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