Re: [Documentation] What gives the most bang for the buck?
On 12/18/2012 12:25 PM, Rob Weir wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. I know there has been talk about getting started guides, perhaps done on the wiki. Another idea I had was a very targeted version of that, thinking specifically of Microsoft Office users migrating to OpenOffice. Would it be worth having a small guide just for them, say the top 10 helpful hints for MS Office users, things they might find confusing at first. For example: 1) In Calc, the argument separator is a semi-colon, not a comma. 2) In Calc, toggling absolute address mode is done by a shift-F4, not an F4 OK. Maybe we end up more with 40 or 50 things like this. Would this be useful and worth trying? -Rob I realize I am a bit late in reviewing this thread. However, here's a site I came across: http://www.linuxtopia.org/online_books/office_guides/microsoft_office_to_openoffice_migration/index.html -- and a specific example http://www.linuxtopia.org/online_books/office_guides/microsoft_office_to_openoffice_migration/openoffice_migration_Keyboard_shortcuts_0606MG-DifferencesInUseCalcExcel.html info is for OO.o 3.2. See licensing details. Maybe we can use it. -- MzK No act of kindness, no matter how small, is ever wasted. -- Aesop
Re: [Documentation] What gives the most bang for the buck?
On Wed, Dec 19, 2012 at 2:01 AM, Andrew Douglas Pitonyak and...@pitonyak.org wrote: On 12/18/2012 03:25 PM, Rob Weir wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. May I assume that the ODF Authors site and methods will not be used (initial intent was to have both supported) and that a separate effort and site will be used? If yes, then: My assumptions are that the work is done on Apache lists, wikis and website, that the work products are published at Apache, under the Apache License. I'm not sure what the ODF Authors methods are, but I have no assumptions on whether they should be used or not. 1. Decide what to produce (content such as FAQ, User guides, etc) 2. Establish target output types (ODT files, PDF, eBook, Web pages) 2a) Establish editing format that can be transformed into the target output types. 3. Pick a tool and decide how it will be used; for example, if using AOO, is it one big document or using Master Documents? The modularity aspect is key. For example, if we write self-contained topics then we can assemble them into different larger works. So imagine we had a topic for every menu item and dialog in the product. Put that together, along with conceptual topics (like why styles are important) and you have a comprehensive reference manual. But a subset of this material might be brought together, along with new specific target, for a shorter work, Writing your Dissertation with Apache OpenOffice, or Apache OpenOffice for Science and Engineering, or Apache OpenOffice for Microsoft Office Users. Some might be purely text. Some might have video demonstrations to accompany them for key techniques. This old TED talk gives the key insight, I think: http://www.ted.com/talks/malcolm_gladwell_on_spaghetti_sauce.html The question should not be how to create the single perfect user's guide that makes the most people happy. It should be (IMHO) how do we efficiently create many guides that fit our diverse user base even better than any single guide could do. 4. Establish a workflow 4a) NL translation should be explicitly considered when defining tooling, workflows, etc. 5. Create uniform templates 6. Document how volunteers work 7) Establish a feedback loop with our users/readers Now, for each produced document, probably the most difficult part is the initial outline for each document. -- Andrew Pitonyak My Macro Document: http://www.pitonyak.org/AndrewMacro.odt Info: http://www.pitonyak.org/oo.php
Re: [Documentation] What gives the most bang for the buck?
On Wed, Dec 19, 2012 at 12:36 AM, Stephen Cameron steve.cameron...@gmail.com wrote: Hi Rob, I agree with your points, It should be possible to create something using the AOO Writer by borrowing the DITA concepts rather than the standard itself, maybe by using templates. The key concept is to be able to generate big documents from lots of smallish, very specifically focused, ones. This provides many advantages (as reading an intro to DITA will make clear) but regarding managing the 'content' development process and in the usefulness of the end result. Potentially the DITA open toolkit can be tweeked to accept something different, its all XML behind the scenes in ODF I assume. From another direction, maybe we can find a way to convert AOO output (in ODF format) into proper DITA? There might we away that this could be done using a combination of styles and metatags inserted into the text of the document. -Rob On Wed, Dec 19, 2012 at 12:22 PM, Rob Weir robw...@apache.org wrote: On Tue, Dec 18, 2012 at 7:15 PM, Stephen Cameron steve.cameron...@gmail.com wrote: Hi, Have you ever thought of DITA as an option for AOO documentation? I've just started using it for documentation of some non-commercial software. There is an FOSS resource in the DITA Open Toolkit. In theory the DITA concepts are resources from which is generated different types of documentation via DITA maps. http://dita-ot.sourceforge.net/ If coders created DITA topics as feature where implemented then these could be taken and used by people creating documentation. This just might overcome one of the major limitations of many open-source projects, poor documentation. I certainly have suggested DITA as an approach. It has the advantages of being able to target PDF, HTML, e-Book., etc. It also would allow us to do a greater degree of customization, e.g., encode what paragraphs are Linux-specific, etc., and then generate a guide for windows, another one for Linux, etc., from a single source document. However, the arguments against DITA that I've heard include: 1) Volunteers are not familiar with it. So it becomes an additional hurdle for contributors 2) Editing DITA via raw XML is hard, but the good DITA editors that make DITA editing easy are not free. 3) Since our project includes its own word processor, we should probably use it for producing documentation. I don't think these hurdles are impossible to overcome, but we'd need to figure out how to do so. IMHO learning DITA is not very hard. You don't need to be a programmer, for example. And knowledge of DITA is a useful market skill. So if we did a call for documentation volunteers and talked about this being an opportunity to gain experience with DITA, that might be attractive to some new volunteers. On the other hand, some just want to write, and not worry about a more complicated document preparation workflow. Regards, -Rob On Wed, Dec 19, 2012 at 10:03 AM, Keith N. McKenna keith.mcke...@comcast.net wrote: Rob Weir wrote: On Tue, Dec 18, 2012 at 4:28 PM, Keith N. McKenna keith.mcke...@comcast.net wrote: Donald Whytock wrote: Hotkey reference pages? My personal preference for documentation is usually immediate-answer stuff like reference pages and very specific how-tos, as opposed to general guides and introductions. Perhaps that's just me coming from a programming perspective. Don Don; Immediate answer pages are great and they serve a useful purpose. However there is also need for In depth Guides and Introductions such as the Getting Started Guides. There are still many of us that prefer to have hard copy documentation that we can highlight and mark-up as fits our learning styles. With hypertext we can have both, right? Immediate answer pages that link to in depth reference material for details, etc. -Rob Rob; That is correct. That is one nice thing about electronic documentation. Regards Keith Regards Keith On Tue, Dec 18, 2012 at 3:25 PM, Rob Weir robw...@apache.org wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. I know there has been talk about getting started guides, perhaps done on the wiki. Another idea I had was a very targeted version of that, thinking specifically of Microsoft Office users migrating to OpenOffice. Would it be worth having a small guide just for them, say the top 10 helpful hints for MS Office users, things they might find confusing at first. For example: 1) In Calc, the argument separator is a semi-colon, not a comma. 2) In Calc, toggling absolute address mode is done by a shift-F4, not an F4 OK. Maybe we end up more with 40 or 50 things like this. Would this be useful and worth trying? -Rob
Re: [Documentation] What gives the most bang for the buck?
Rob Weir wrote: On Wed, Dec 19, 2012 at 12:36 AM, Stephen Cameron steve.cameron...@gmail.com wrote: Hi Rob, I agree with your points, It should be possible to create something using the AOO Writer by borrowing the DITA concepts rather than the standard itself, maybe by using templates. The key concept is to be able to generate big documents from lots of smallish, very specifically focused, ones. This provides many advantages (as reading an intro to DITA will make clear) but regarding managing the 'content' development process and in the usefulness of the end result. Potentially the DITA open toolkit can be tweeked to accept something different, its all XML behind the scenes in ODF I assume. From another direction, maybe we can find a way to convert AOO output (in ODF format) into proper DITA? There might we away that this could be done using a combination of styles and metatags inserted into the text of the document. -Rob Rob; This may be a better alternative. That way standard templates could be developed and contributors would be able to concentrate more on writing than on learning DITA. Regards Keith On Wed, Dec 19, 2012 at 12:22 PM, Rob Weir robw...@apache.org wrote: On Tue, Dec 18, 2012 at 7:15 PM, Stephen Cameron steve.cameron...@gmail.com wrote: Hi, Have you ever thought of DITA as an option for AOO documentation? I've just started using it for documentation of some non-commercial software. There is an FOSS resource in the DITA Open Toolkit. In theory the DITA concepts are resources from which is generated different types of documentation via DITA maps. http://dita-ot.sourceforge.net/ If coders created DITA topics as feature where implemented then these could be taken and used by people creating documentation. This just might overcome one of the major limitations of many open-source projects, poor documentation. I certainly have suggested DITA as an approach. It has the advantages of being able to target PDF, HTML, e-Book., etc. It also would allow us to do a greater degree of customization, e.g., encode what paragraphs are Linux-specific, etc., and then generate a guide for windows, another one for Linux, etc., from a single source document. However, the arguments against DITA that I've heard include: 1) Volunteers are not familiar with it. So it becomes an additional hurdle for contributors 2) Editing DITA via raw XML is hard, but the good DITA editors that make DITA editing easy are not free. 3) Since our project includes its own word processor, we should probably use it for producing documentation. I don't think these hurdles are impossible to overcome, but we'd need to figure out how to do so. IMHO learning DITA is not very hard. You don't need to be a programmer, for example. And knowledge of DITA is a useful market skill. So if we did a call for documentation volunteers and talked about this being an opportunity to gain experience with DITA, that might be attractive to some new volunteers. On the other hand, some just want to write, and not worry about a more complicated document preparation workflow. Regards, -Rob On Wed, Dec 19, 2012 at 10:03 AM, Keith N. McKenna keith.mcke...@comcast.net wrote: Rob Weir wrote: On Tue, Dec 18, 2012 at 4:28 PM, Keith N. McKenna keith.mcke...@comcast.net wrote: Donald Whytock wrote: Hotkey reference pages? My personal preference for documentation is usually immediate-answer stuff like reference pages and very specific how-tos, as opposed to general guides and introductions. Perhaps that's just me coming from a programming perspective. Don Don; Immediate answer pages are great and they serve a useful purpose. However there is also need for In depth Guides and Introductions such as the Getting Started Guides. There are still many of us that prefer to have hard copy documentation that we can highlight and mark-up as fits our learning styles. With hypertext we can have both, right? Immediate answer pages that link to in depth reference material for details, etc. -Rob Rob; That is correct. That is one nice thing about electronic documentation. Regards Keith Regards Keith On Tue, Dec 18, 2012 at 3:25 PM, Rob Weir robw...@apache.org wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. I know there has been talk about getting started guides, perhaps done on the wiki. Another idea I had was a very targeted version of that, thinking specifically of Microsoft Office users migrating to OpenOffice. Would it be worth having a small guide just for them, say the top 10 helpful hints for MS Office users, things they might find confusing at first. For example: 1) In Calc, the argument separator is a semi-colon, not a comma. 2) In Calc, toggling absolute address mode is done by a shift-F4, not an F4 OK. Maybe we end up more with 40 or 50 things like this. Would this be useful and
Re: [Documentation] What gives the most bang for the buck?
Hotkey reference pages? My personal preference for documentation is usually immediate-answer stuff like reference pages and very specific how-tos, as opposed to general guides and introductions. Perhaps that's just me coming from a programming perspective. Don On Tue, Dec 18, 2012 at 3:25 PM, Rob Weir robw...@apache.org wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. I know there has been talk about getting started guides, perhaps done on the wiki. Another idea I had was a very targeted version of that, thinking specifically of Microsoft Office users migrating to OpenOffice. Would it be worth having a small guide just for them, say the top 10 helpful hints for MS Office users, things they might find confusing at first. For example: 1) In Calc, the argument separator is a semi-colon, not a comma. 2) In Calc, toggling absolute address mode is done by a shift-F4, not an F4 OK. Maybe we end up more with 40 or 50 things like this. Would this be useful and worth trying? -Rob
Re: [Documentation] What gives the most bang for the buck?
Donald Whytock wrote: Hotkey reference pages? My personal preference for documentation is usually immediate-answer stuff like reference pages and very specific how-tos, as opposed to general guides and introductions. Perhaps that's just me coming from a programming perspective. Don Don; Immediate answer pages are great and they serve a useful purpose. However there is also need for In depth Guides and Introductions such as the Getting Started Guides. There are still many of us that prefer to have hard copy documentation that we can highlight and mark-up as fits our learning styles. Regards Keith On Tue, Dec 18, 2012 at 3:25 PM, Rob Weir robw...@apache.org wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. I know there has been talk about getting started guides, perhaps done on the wiki. Another idea I had was a very targeted version of that, thinking specifically of Microsoft Office users migrating to OpenOffice. Would it be worth having a small guide just for them, say the top 10 helpful hints for MS Office users, things they might find confusing at first. For example: 1) In Calc, the argument separator is a semi-colon, not a comma. 2) In Calc, toggling absolute address mode is done by a shift-F4, not an F4 OK. Maybe we end up more with 40 or 50 things like this. Would this be useful and worth trying? -Rob
Re: [Documentation] What gives the most bang for the buck?
On Tue, Dec 18, 2012 at 4:28 PM, Keith N. McKenna keith.mcke...@comcast.net wrote: Donald Whytock wrote: Hotkey reference pages? My personal preference for documentation is usually immediate-answer stuff like reference pages and very specific how-tos, as opposed to general guides and introductions. Perhaps that's just me coming from a programming perspective. Don Don; Immediate answer pages are great and they serve a useful purpose. However there is also need for In depth Guides and Introductions such as the Getting Started Guides. There are still many of us that prefer to have hard copy documentation that we can highlight and mark-up as fits our learning styles. With hypertext we can have both, right? Immediate answer pages that link to in depth reference material for details, etc. -Rob Regards Keith On Tue, Dec 18, 2012 at 3:25 PM, Rob Weir robw...@apache.org wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. I know there has been talk about getting started guides, perhaps done on the wiki. Another idea I had was a very targeted version of that, thinking specifically of Microsoft Office users migrating to OpenOffice. Would it be worth having a small guide just for them, say the top 10 helpful hints for MS Office users, things they might find confusing at first. For example: 1) In Calc, the argument separator is a semi-colon, not a comma. 2) In Calc, toggling absolute address mode is done by a shift-F4, not an F4 OK. Maybe we end up more with 40 or 50 things like this. Would this be useful and worth trying? -Rob
Re: [Documentation] What gives the most bang for the buck?
Rob Weir wrote: On Tue, Dec 18, 2012 at 4:28 PM, Keith N. McKenna keith.mcke...@comcast.net wrote: Donald Whytock wrote: Hotkey reference pages? My personal preference for documentation is usually immediate-answer stuff like reference pages and very specific how-tos, as opposed to general guides and introductions. Perhaps that's just me coming from a programming perspective. Don Don; Immediate answer pages are great and they serve a useful purpose. However there is also need for In depth Guides and Introductions such as the Getting Started Guides. There are still many of us that prefer to have hard copy documentation that we can highlight and mark-up as fits our learning styles. With hypertext we can have both, right? Immediate answer pages that link to in depth reference material for details, etc. -Rob Rob; That is correct. That is one nice thing about electronic documentation. Regards Keith Regards Keith On Tue, Dec 18, 2012 at 3:25 PM, Rob Weir robw...@apache.org wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. I know there has been talk about getting started guides, perhaps done on the wiki. Another idea I had was a very targeted version of that, thinking specifically of Microsoft Office users migrating to OpenOffice. Would it be worth having a small guide just for them, say the top 10 helpful hints for MS Office users, things they might find confusing at first. For example: 1) In Calc, the argument separator is a semi-colon, not a comma. 2) In Calc, toggling absolute address mode is done by a shift-F4, not an F4 OK. Maybe we end up more with 40 or 50 things like this. Would this be useful and worth trying? -Rob
Re: [Documentation] What gives the most bang for the buck?
Hi, Have you ever thought of DITA as an option for AOO documentation? I've just started using it for documentation of some non-commercial software. There is an FOSS resource in the DITA Open Toolkit. In theory the DITA concepts are resources from which is generated different types of documentation via DITA maps. http://dita-ot.sourceforge.net/ If coders created DITA topics as feature where implemented then these could be taken and used by people creating documentation. This just might overcome one of the major limitations of many open-source projects, poor documentation. On Wed, Dec 19, 2012 at 10:03 AM, Keith N. McKenna keith.mcke...@comcast.net wrote: Rob Weir wrote: On Tue, Dec 18, 2012 at 4:28 PM, Keith N. McKenna keith.mcke...@comcast.net wrote: Donald Whytock wrote: Hotkey reference pages? My personal preference for documentation is usually immediate-answer stuff like reference pages and very specific how-tos, as opposed to general guides and introductions. Perhaps that's just me coming from a programming perspective. Don Don; Immediate answer pages are great and they serve a useful purpose. However there is also need for In depth Guides and Introductions such as the Getting Started Guides. There are still many of us that prefer to have hard copy documentation that we can highlight and mark-up as fits our learning styles. With hypertext we can have both, right? Immediate answer pages that link to in depth reference material for details, etc. -Rob Rob; That is correct. That is one nice thing about electronic documentation. Regards Keith Regards Keith On Tue, Dec 18, 2012 at 3:25 PM, Rob Weir robw...@apache.org wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. I know there has been talk about getting started guides, perhaps done on the wiki. Another idea I had was a very targeted version of that, thinking specifically of Microsoft Office users migrating to OpenOffice. Would it be worth having a small guide just for them, say the top 10 helpful hints for MS Office users, things they might find confusing at first. For example: 1) In Calc, the argument separator is a semi-colon, not a comma. 2) In Calc, toggling absolute address mode is done by a shift-F4, not an F4 OK. Maybe we end up more with 40 or 50 things like this. Would this be useful and worth trying? -Rob
Re: [Documentation] What gives the most bang for the buck?
On 12/18/2012 03:25 PM, Rob Weir wrote: As we wait, patiently, for the new doc list to be created, it might be worth having a quick discussion about priorities. May I assume that the ODF Authors site and methods will not be used (initial intent was to have both supported) and that a separate effort and site will be used? If yes, then: 1. Decide what to produce (content such as FAQ, User guides, etc) 2. Establish target output types (ODT files, PDF, eBook, Web pages) 3. Pick a tool and decide how it will be used; for example, if using AOO, is it one big document or using Master Documents? 4. Establish a workflow 5. Create uniform templates 6. Document how volunteers work Now, for each produced document, probably the most difficult part is the initial outline for each document. -- Andrew Pitonyak My Macro Document: http://www.pitonyak.org/AndrewMacro.odt Info: http://www.pitonyak.org/oo.php
