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