Date: Jun 27, 2007 2:20 PM Subject: [documentation-dev] OOo documentation for non-OOo Users (was: Two uses for PDFs of some OOo docs)
OK, thanks for this, and I agree it makes a lot of sense, especially the importance of understanding the audience / "needs of the consumers". I disagree, however, with the implied statement that the only cost of providing alternate forms of the documentation is "one click to produce a PDF"; see Background and below. Background: An IT principle (actually, it's older than that) is to store any one piece of information in only one place. A consequence of violating this principle is confusion for the users when they notice differences among multiple sources. A worse consequence is that they make decisions based on obsolete information, which errors could have been prevented simply by avoiding production of more than one form/repository of the information. Sometimes either or both of these consequences result in extra wasted resources for the providers to answer questions and address problems, mostly to un-confuse those users. Applying this principle to OOo documentation, there should be exactly one System of Record with the current version (and perhaps other versions, but clearly marked) of the documentation, and production of any other forms of that same information should be carefully considered as to production and maintenance cost -- including the work of keeping track of the multiple copies, when they should be updated, etc. -- and ROI for that work. Now, I'd like to try to help document where we are in at least one half of the ROI question (the benefits of PDFs or any non-ODT/ODF format), and I invite everyone to build on / clarify / debunk and replace / etc. the "logical syllogism' I start here (it's not formal/complete, but I hope it serves adequately): 1. (Basic Premise:) The purpose of OOo documentation is to help people understand how to use / benefit from OOo software. (Categorization:) Those people either (a) have OOo software installed or (b) they don't. Or in other words, the documentation is to help them (a) to learn more about using / benefitting from the OOo software they have, or (b) to decide whether to get/use OOo software. 1. a. If they already have OOo software, they have no use for PDF or any other non-OOo-native documentation, and any such files provided are wasted effort for the producers, and restrictive extra junk to delete for the users. 1. b. (Conclusion 1:) Therefore, the non-OOo-native documentation (which apparently will include the original sources) is what non-OOo users will read in order to decide whether to get/use OOo software. (Categorization of Conclusion:) The complete list of possibilities for this non-OOo-native documentation is / will be (is this correct?): 1. b. 1. The original sources on an OO.org WWW server, HTML / other web-browser-readable, e.g. text, though text is inadequate in many languages. 1. b. 2. PDFs on an OO.org WWW server, produced from the sources, but not always completely up-to-date. 1. b. 3. Original docs on an OO.org WWW server, written in e.g. OOo Writer and provided to OO.org in that format. * 1. b. 4. PDFs, and/or the web-browser-compatible original sources in an HTML tree, on CD. * Does/will this ever happen, in the new system? If yes, those inputs could be immediately converted to PDF (or HTML) reliably, perfectly, and easily with the famous one-button-push, to support non-OOo users who want to read the latest inputs and know how to find them -- how many of these users are there? -- but those OOo-native files would probably only be input to further work / new versions in HTML; correct? If HTML supports Natural/National Language and character sets well enough, then why add work to duplicate them to PDF? The Installation Instructions must always be "golden" and in the appropriate Natural/National Language and its character set; PDF or HTML may well be the best means of providing these. See for example Unicode considerations at http://www.w3.org/WAI/GL/2000/12/pdf.html PDF Techniques for Web Content Accessibility Guidelines. 1. c. Further, these non-OOo users may want to print the documentation on paper (a few may want to load it on an e-book reader) and read it away from their computers or not; they may get it via the Internet or a CD; and their means to read it may or may not be an Internet-connected computer. 2. We can eliminate some scenarios from the list of those that would benefit from the provision of PDF docs: 2. a. If the means of reading is an Internet-connected computer, then the HTML source pages are best / most-current. 2. b. If the users want to print it and read it later, they can print the HTML source pages directly (especially if there is provided a utility for doing this efficiently), plus they can adjust font size, margin etc. before printing. 2. c. From 1. c. thru 2. b. above we conclude that the only scenarios of interest for providing PDF documentation are those for non-OOo users who have no access to an Internet-connected computer with printer, and they acquire an OOo CD (and OpenOffice.org may not know they have it) and a means to read its (e.g. PDF or HTML) docs (and possibly to print them), i.e. a computer that is not Internet-connected, and HTML does not provide comparable support e.g. for their language. 3. Given the audience defined in 2. c. above, have we now defined the benefit question to be, "What is the best way to provide non-OOo-native documentation, but only on CD, and to a very small number of persons, most of which can not or will not ever become significant users of OOo anyway, because they lack the will or means or both?" If no, we need to correct this. Then we can move on to how to best meet this goal. 4. The best means of providing maximum benefit to even this small number of potential users (with, happily, minimum cost to the providers), it seems to me, is to simply provide the Installation Instructions on the CD in (of course) non-OOo-native format (I would use HTML or PDF or similar -- see 1.b.3 above -- to support their Natural/National Language) and advise in that same file or the README to open the documentation files after installation. This gives the new user the opportunity (OK, it forces them) to actually try OOo software while reading the documentation (probably in the _same_ _window_!), which is a very good way to learn and helps to convince the new user that this OOo stuff is really easy to install and use (e.g. to switch to from M$ Office and the like). ====> I am assuming above the statement from some on this list that the documentation provided on the OOo CDs will always include the complete set in OOo native formats -- is this still true? IHTH -- Does this kind of thinking actually help, or am I mostly wasting everyone's time? Feel free to correct me on-list. Jim >>> [EMAIL PROTECTED] 4:23 PM 6/25/200725/2007 >>> marbux wrote: > On 6/25/07, Jim Harris <[EMAIL PROTECTED]> wrote: >> However, I still don't see how a PDF on an OOo CD (or for an OOo user) >> does anything that a native OOo document does not do at least as well It works for people who haven't yet installed OOo (or any other program that reads ODT files). That is particularly relevant to people who get CDs, or use them at the local library or senior citizens' centre. >> Further, the OOo files (and many other standard formats) have the huge >> advantage of editability > > > I'd argue that PDF has very significant disadvantages, with difficulty > editing being right at the top of the list. In my mind, documentation is > less than optimal if it can't easily be edited by the user. I have never argued that PDF should be the only distribution method for documentation, nor that it is the best. My argument is for a range of distribution methods that serve the needs of different audiences. No one form serves the needs of all audiences. I appreciate Jim's and others' arguments about ROI, which I will respond to in a different note. BTW, the only reason that the OOo Docs site has only PDFs of the OOoAuthors books is that OOo won't let us put the ODTs there, because of licensing issues. --Jean
