marbux 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
Like marbux noted, this is an ideal hardly ever reached. This would also require everyone to have access the one location that holds the information. Instead, we need to think about one information source and different delivery formats. The source being in one single place where ideally users can contribute to it. The delivery format would allow to distribute the information in accordance to the user's needs. [...] >> 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): Folks, producing a PDF really is not that big a deal. Once we have a common template that makes it look professional (and thus credible) it's merely more than a click (as Jean said). And a template would be needed for ODF as well. [...] > 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. This is why we are looking at the wiki because it offers all users the possibility to contribute. Starting from wiki we may then produce several formats for the various channels and users. The argument for distributing ODF to the users to allow them to modify the doc is not convincing to me because I don't want them to modify the docs in their personal sphere but contribute back to the community and improve and enrich the sources for everyone. This is hard to accomplish using ODF (try to merge multiple ODFs). It's easier with a wiki (or a similar system). > 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. I fully agree. [...] > 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. I don't know of any OS that comes without a PDF reader. And if there are some, the target audience for these OSs may not really match the audience for those PDFs anyway. Besides, the multitude of browsers and versions makes it much harder to control the layout of XHTML than PDF. And particularly beginners may easily be alienated by unreadable or corrupted (X)HTML page display and may as well blaim OOo for that. > 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. I don't see that we have the time nor resources to come up with a revolutionary documentation system. There are many places where the current system needs improvement. We should take evolutionary steps with this system, learn gradually, and implement what we learned. What we really need is the right mixture of process and pragmatism or we'll either be drowning in chaos or get forever stuck in discussions about what a good doc system would be. > 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." Yeah, that's what we need. Concrete suggestions. This one would be relatively easy to implement once we have the help on the wiki for collaboration. Add a link on every help page that points to the corresponding wiki page to allow for discussions, fixes, amendments. Jim, marbux thanks for this great discussion Frank -- Frank Peters, Co-Lead 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]
