Re: [User Docs] What do we as a community want for user documentation or AOO
2012/9/20 RGB ES > 2012/9/16 Keith N. McKenna > >> 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. Regards Ricardo (1) http://wiki.openoffice.org/wiki/ES/Manuales/GuiaAOO
Re: [User Docs] What do we as a community want for user documentation or AOO
Hi Ricardo, 2012/11/12 RGB ES > 2012/9/20 RGB ES > > > 2012/9/16 Keith N. McKenna > > > >> 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. > It's a good approach for an online documentation. This reduces its volume and simplifies the updates. By the way, I have good results when I translate your texts in french with Google Translator. I can easy understand all even I don't know any word in spanish. Many thanks for this work under Alv2.0. > > > (1) http://wiki.openoffice.org/wiki/ES/Manuales/GuiaAOO A+ -- gw
Re: [User Docs] What do we as a community want for user documentation or AOO
On Sun, Nov 11, 2012 at 9:07 PM, RGB ES wrote: > 2012/9/20 RGB ES > >> 2012/9/16 Keith N. McKenna >> >>> 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
Re: [User Docs] What do we as a community want for user documentation or AOO
2012/11/12 Rob Weir > On Sun, Nov 11, 2012 at 9:07 PM, RGB ES wrote: > > 2012/9/20 RGB ES > > > >> 2012/9/16 Keith N. McKenna > >> > >>> 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 >
Re: [User Docs] What do we as a community want for user documentation or AOO
On Tue, Nov 13, 2012 at 5:05 PM, RGB ES wrote: > 2012/11/12 Rob Weir > >> On Sun, Nov 11, 2012 at 9:07 PM, RGB ES wrote: >> > 2012/9/20 RGB ES >> > >> >> 2012/9/16 Keith N. McKenna >> >> >> >>> 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.ibmpre
Re: [User Docs] What do we as a community want for user documentation or AOO
2012/11/13 Rob Weir > On Tue, Nov 13, 2012 at 5:05 PM, RGB ES wrote: > > > 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. > A chapter with a collection of quick "cheat sheets" could be a good idea, indeed: "to do 'this', follow 'these steps' and for more info see 'here'". Regards Ricardo > > 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. > > >
