> I'm not an expert - to be honest I hoped to meet the experts here ;-) > but on the German community mailing list we had a discussion if it > makes sense to use the wiki for documentation at all - as this raises > the problem of double bookkeeping and of converting documents. A > possible solution would be to use a common Master. So my question > should have been: does it make sense to consider a general setting with > DocBook as master for all documents? I don't know if there are good > docbook->odt or docbook->wiki filters but from theory this seems more > straightforward than odt->wiki and vice versa. > > BTW - I don't see any problems in using specialized tools for special > goals, think of the issue tracker, pootle, Plone etc. The word > processor serves for creating nice documents, the question addressed > here is more to generate different output formats from the same content > source.
One of the big reasons we moved/pushed towards using the Wiki for docs is.. to try and get more community involvement... basically lowering the entry barrier to editing the docs. In at least some documents, this has worked quite well. The Wiki is easy to access, and anyone with a browser can participate. We're just getting those people interested and some are starting to get involved. If we choose to use some other application that must be installed separately or some special OOo configuration requiring plugins and user IDs on certain webservers etc., we will immediately eliminate a segment of contributors, and the doc workload falls back 100% to a very very small team of maybe 3 or 4 people. The example I have is the DevGuide. Before porting it to the Wiki, it was developed in a custom process that required a specific StarOffice version with a special plugin for reading the custom XML sourcefile type. Only someone who had access to this version of StarOffice and could get the plugin could open the source files and edit. This meant basically... 2 people were working on the source and creating the doc. All of the developers had to push their doc changes through these two people. The community had no hope of contributing things like code snippets and making corrections except through raising Issues in the OOoIssue tracker. With this doc in the Wiki, it is subject to a steady stream of edits by developers and community members who keep the doc much more current, and who are adding example code and other helpful bits. One of the issues with working direct in DocBook is that it does require a significant level of expertise, and we're raising that entry bar way up again. Personally I like DocBook, and have written a lot of documentation in raw XML and DocBook... but it's not easy... requires at least some custom tooling in the process etc, and at least some measure of technical skill above your average computer user level - even if you're using a DocBook editor of some sort. If we argue that we can use Writer as a DocBook editor (it is technically possible to export DocBook from Writer), then why bother with DocBook? Do the docs right in ODT. No matter which way we go (Wiki, DocBook, or something else), we will have issues. If we use a CMS of some sort and Writer (TeamDrive and Alfresco, to name two, have OOo plugins so you can access the files direct from OOo), we loose a lot of the simple accessibility that we have in the Wiki. If we use the Wiki, we have difficulty exporting to other formats. The Wiki is definitely not a perfect medium for documenting, but... it does the job reasonably OK in most cases. In a perfect world, I'd like to be able to use OOoWriter to author and edit the docs, save them to webserver (just via save), and be able to automatically/immediately have them rendered into Webpages (as in the way the Wiki works). There is not yet a OOo based Wiki :-) It'd be the best of both worlds. C. -- Clayton Cornell ccorn...@openoffice.org OpenOffice.org Documentation Project co-lead StarOffice - Sun Microsystems, Inc. - Hamburg, Germany --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
