On 7/2/07, Jim Harris <[EMAIL PROTECTED]> wrote:
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.
Maintenance of single editing points for recurrent information is the Holy Grail of document assembly. Many wikis and content management systems include tools for accomplishing that task, though they are seldom used, I suspect because cut and paste is such an ingrained habit. Probably the FOSS content management system best suited for such tasks is Daisy, < http://www.cocoondev.org/daisy/index.html>. Its front end is a wiki, overlying a content repository, but it is a full blown document assembly tool with strong tools for inclusion (maintaining a single editing point for recurrent content. It also happens to write to ODT and indexes ODT's (and other formats including PDF) as part of its site search engine. One of its stronger features for the purposes of this discussion is Variants:
Variants A document can exist in multiple variants. Each variant has its own version history. Each variant is basically a different copy of the same document. There are two types of variants: branches and languages. Language variants are useful to maintain documents in multiple languages, while branch variants allow parallel maintenance of different 'versions' of a document. Branches are often useful for software documentation, for example Daisy's own documentation has a branch for each major version. <<< And for long documents:
Book publishing The book publishing component allows for the generation of professionally formatted books with table of contents, section numbering, cross-referencing, footnotes, index, lists of images and tables, etc. It goes much further than simply concatenating some pages. Headers in documents are shifted based on their hierarchical position within the book, and when doing a chunked-HTML publication, the chunking is performed irrespective of the boundaries of the original documents. Books can be produced in a variety of formats, HTML and PDF publications are included by default. Books are generated as a batch process, the end-result is a static book publication that could be put on a static web server or a compact disc. <<< <http://www.cocoondev.org/daisy/features.html>
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.
I'm not sure this premise holds all the water that it tries to put in the pail. As some have noted, some folks prefer PDF for various reasons, including the ability to print documentation into a dead tree book. I am not a fan of PDF for that purpose, but it does have the advantage over HTML in that it is far easier to paginate PDF to conform to paper sizes. On the other hand, I would agree that native ODT would be preferable in some ways, in part because it is more easily editable so a user can add his/her own annotations/sections. But if we could get past the pagination hurdle (and we can with some apps), I would prefer that all documentation (including internal Help) be generated in XHTML. Frankly, I think one of the biggest failings of free and open source software has been to largely clone the Microsoft approach to documentation, which was explicitly designed to require expert Help authors and provided no tools for users to **easily** contribute to documentation efforts. Having contributed a lot of time in the old days to doing volunteer tech support for WordPerfect, I found it amazing how often I found myself answering the same questions over and over again, ad nauseum. I tried to persuade Corel to export the Help files to HTML and give us editing rights so we could fill the holes, and to make it possible for folks to download updated Help files on demand, but no joy there. As a general (constructive) criticism, I think we have too much of that kind of thing in the guide development work too. E.g., it requires expertise beyond that of a normal OOo user to contribute to documentation in bite size hunks. It takes a pretty deep dive into the documentation for creating documentation to contribute and should be far easier. I think the energy for using a wiki is partly responsive to that problem, but I hope we might find ways to make it even easier. All of those folks who have taken the time to figure out how to do something that isn't adequately explained in the documentation are a tremendous asset if we can give them the tools they need to contribute easily. Somewhat more relaxed permissions on the wiki might help in that regard. Versioning gives us the ability to revert to the extent we get non-useful content and if I recall correctly, Mediawiki has the tools to moderate content before it is published. 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.
XHTML rather than HTML, please. Much more can be done with it in terms of recycling/converting content. * 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.
The pagination problem rears its ugly head here again. 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.
XHTML would be better than PDF. Many FOSS distributions do not provide a PDF reader by default, but I've never heard of an OS distributed without a browser since the CP/M - DOS days. 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.
I think it's a valuable contribution, notwithstanding my relatively minor criticisms. But I think an even more valuable approach might be to involve a systems analyst and usability expert to design a documentation system from scratch. What we have now is largely a patchwork approach that is absolutely unfriendly to user contributions to documentation. We don't have the right software for such contributions or for managing documentation development and distribution. This is only a small illustration, but where might we be two years from now if the OOo Help menus each had a selection for "Submit documentation enhancement" that popped up a form for filling in needed information ( e.g., which app and feature(s) it applies to) and a space for filling in a narrative with a "submit" button at the bottom? Or opened an ODT template so folks could do formatting, add screengrabs, etc? With maybe an option to "mail me back the tracker number, please."
>>> [EMAIL PROTECTED] 4:23 PM 6/25/200725/2007 >>>
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.
I didn't mean to suggest that you did, Jean. Sorry if you understood it that way. And of course you are right that there is no one-size fits all solution. But I think that Jim has an excellent point that there should be a single document of record and a system for managing variants. I think a system along the lines of Daisy could be of significant benefit as could its ability to maintain a single editing point for recurring content.. Best regards, Marbux
