On Friday 04 September 2009 15:55, Clayton wrote: > > 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.
ok, I've understood that it has not been a technical reason to give the wiki a try but community involvement. It's good to keep this in mind. > 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. But with the User Guides - did you experience a higher contribution activity up to now? As far as I've seen the English Guides have been in the wiki for quite a year now? > 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. Sorry, I've never been using it so I did not know the skill level needed. > 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. But in docbook the filters already exist for several output formats. And they are maintained by others. With ODT, hasn't all this to be generated again? (just a question) > 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. For me at the moment, the above argument (community involvment) seems the most important. > 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. Ok, but this seems (far) in the future (for me at least). Another present concern is that the wiki in it's actual structure is not very attractive to end users. It is not very usable. Main issues are IMHO: it serves for several purposes spread too wide apart (development and community and end user documentation), search cannot be restricted to one language (or e.g. one version or one purpose), and some of the pages are of questionable quality or even "trial pages". Good end user documentation has to be very clearcut and clean, it is measured by its usability. And only a good, promising set-up attracts people. So the goal "community involvement" seems to be foiled to a certain extent by the suboptimal realization. Nino --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
