In "... many users still value a [book-type] manual that they can download, print out and read offline. So there is still the need for creating PDF files", I agree with the goals and premise, but not the conclusion. This is one of my "pet peeves" about most help-style documentation: When the user wants to know how to use the product, and after looking through all pages found via various search efforts, still has not found what was sought, he/she wants to answer the question, "Have you read the manual?", either for themselves or for someone else who is trying to help them. With help-style documentation this can be impossible. Therefore, we users who want to "read the manual" need some way of assuring ourselves that we have read (or printed) the entire manual, preferably in some orderly way, e.g. at least pages are grouped by topic. However, a PDF is not the only way to achieve this goal. Any feature that allows a user to "walk" a documentation tree, e.g. "always turn left" or "do this element and all its descendants", preferably marking where he/she has been, will achieve that goal. If you avoid numbering pages consecutively thru the entire "book" but instead number the pages within small blocks/subjects, e.g. III-B-1, III-B-2, etc., or Printing-Pagination-1, Printing-Pagination-2, etc. you never have problems with page numbers. And if, (wonderful world), in combination with the ability to mark on-line (e.g. wiki) pages read, a user could "subscribe" to the on-line manual, so that any user-submitted or steward-approved changed pages / sections (subscriber's choice) would result in automatic notification about those pages / sections, well then, I say we could hold up not only our nifty product but also our nifty documentation service as a model for the world. Just an idea ... I wonder if free software to support all this already exists, e.g. a wiki with steward approval of submitted changes and something like RSS subscription? (Sorry, I don't know about walking the doc structure or marking pages read.) Jim >>> [EMAIL PROTECTED] 3:51:34 PM 6/19/2007 >>>
> I'm mostly a lurker here; I wish I had more time to contribute. > > As something of an observer, it seems to me that there's an elephant in > the room. > > OOo--Writer is what we're talking about of course--is a fine tool for > writing a book, or a PDF version of a book. But books, printed or PDF, > are not the most convenient form for documentation online, which is the > primary access channel for OOo users. > > The question is: is OOo the right tool to use for producing the kind of > documentation we're talking about here? Project-wide scope, with many > sub-documents written by different authors, possibly without central > editorial cleanup, yet cleanly and consistently formatted and available > in a number of different formats. > > I honestly don't know what the best tool is; I'm sure if we took a > survey of what other FLOSS projects are using for their documentation > with similar goals, there would be some standouts. > > I realize there is a huge dog food problem here, but I think the doc > project ought to take a careful look and at least deal with the issue in > the open. Maybe there should be a parallel project to address the > deficiencies in using OOo for this kind of work. > > I guess I just hate to see a lot of community effort going into > re-solving problems that other projects have dealt with successfully, > yet we are struggling with because of the dog food problem. > > Sorry to bring up such a rude question... Joe, thank you, thank you for bringing that up and pointing to the elephant. There is much truth to what you write and actually I think we need to revisit the documentation "strategy" for OOo, meaning how will we produce, maintain, and publish documentation. You mentioned online resources as the primary access channel for users of OOo, so we definitely need to offer documentation in a way that it's easily found online, organized in a way that users find it quickly. For example, organize it by topic type (Troubleshooting, printing, master documents, working with databases, installation, etc) rather than by information type (howto, manual, setup guide). The information would be in chunks that are also easier to maintain collaboratively. A wiki and/or web pages would be the best choice here. On the other hand, many users still value a book type manual that they can download, print out and read offline. So there is still the need for creating PDF files. How do we get these requirements together? First of all, we need to identify which information is best represented using which channel and what does the audience look like. Conceptual and introductory information are well placed in "books" that are read sequentially. The user manuals are an example for that. Instructional information and tips, tricks and troubleshooting for the more advanced users are better placed on channels that allow targeted access to modular information, like the wiki or the application help. For book authoring, we can use OOo although it lacks some of the collaboration features. But you wouldn't want to have too many people collaborating on one book anyway to keep it consistent. The beauty is not only that we're using our dog food but that we also can help testing OOo in what is a highly demanding use case for office suites, namely collaborative editing of large documents, and use our experience to give feedback to the developers. For the other types, we should go wiki, simply because the entry barrier is so low and collaboration so easy. However, working on the wiki has other disadvantages, that we need to look at, like the lack of structure in the text sources (wiki markup generally is very basic). But I would like us to approach this and find solutions to these shortcomings. I am in the process of putting the application help on the wiki (2000+ files), and we will shortly put the developer docs out on the wiki as well. This brings up some issues but I am confident that we will be able to resolve them. So lets move to Documentation.next and see how we can make the docs project better and the primary reference for all help seekers around OOo. BTW: Will anyone of you bet at OOoCon in Barcelona in September? I have handed in a proposal that was accepted for Friday (last session, as usual): http://marketing.openoffice.org/ooocon2007/programme/friday.html I would like us as a project to work on the presentation together. Also, if there are enough of you coming to Barcelona, I could organize a project meeting on Tuesday before the official conference starts. Let me know Frank -- The OOo Documentation Project: SIGN UP - PARTICIPATE - CONTRIBUTE IT'S FREE! NO OBLIGATIONS! http://documentation.openoffice.org http://wiki.services.openoffice.org/wiki/Documentation --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
