Re: [User Docs] What do we as a community want for user documentation or AOO
2012/11/13 Rob Weir robw...@apache.org On Tue, Nov 13, 2012 at 5:05 PM, RGB ES rgb.m...@gmail.com 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.
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 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
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 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*
Re: [User Docs] What do we as a community want for user documentation or AOO
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. Regards Ricardo (1) http://wiki.openoffice.org/wiki/ES/Manuales/GuiaAOO
