On Thu, 2010-09-30 at 10:31 +0200, Clayton wrote: > On 09/30/10 10:17, Jean Hollis Weber wrote: > > Note: I'm talking about *user* guides, not developer or sysadmin docs in > > this note. > > > > We discussed on several occasions whether to provide the user guides in > > wiki formatas well as in PDF and ODT. I'm in favour of using all 3 > > methods as means of reaching different members of the audience, but... > > > > We don't have enough people updating the wiki to keep up with changes in > > the source docs, so some parts of the user guides on the wiki are > > getting more and more out of date. For whatever reasons, the work is not > > getting done. > > > > So... perhaps it's time to drop the wiki version of the user guides? > > Just put a marker on the pages that they are no longer being maintained > > and abandon them until/unless someone can take on the job and do it. > > > > We're having enough difficulty keeping the ODTs up to date, with not > > enough people doing that either. But they are the source from which to > > create PDFs and any other form we want to have the user docs provided > > in. Also, we or others can fairly easily customise those ODTs for other > > flavours of OO, and translators use them too. > > > > Comments? > > > How much effort is it to Wiki-fy a User Guide from ODT source now? I've done > several docs, but not recently. > > What I'm thinking is rather than abandoning the Wiki version... maybe a > process > like this? > - Create/maintain the guides in ODT > - Publish in ODT in the usual places > - Export *once* per release to Wiki (basic export) and *Protect* the Wiki > pages from editing. This allows people to still use the Web versions of the > documents for reference. Since they are locked/static versions, we don't > have > to worry about editing them, or collecting/merging the edits. > > This of course would only work if the export process is not overly involved - > eg > we could look at scripting it and using the WikiBot to do the upload. > > The advantage of this is it provides that 3rd method of accessing the > documentation (which is indexed by Google... which is helpful when you're > trying > to find solutions), and ensures that at least with each release, they are > updated. Abandoning them risks (in my opinion) a bit of a disaster with > obsolete information. > > If exporting is too much work, then it might be better if we removed the Wiki > versions altogether - set up a single referral Wiki page that points to the > ODTs, and redirect all of the old Wiki User Guide pages to the referral link > pages. > > C.
Wikifying the user guides is, in my experience, very fiddly and time consuming even when assisted with TJ's and others' macros to pre-process the output. Chapters need to be broken up into pages, figures need inserting, links need to be created, sometimes the chapter TOCs (in the right-hand sidebar) need amendment. Up to a point some of this can be automated, but afaik not enough to result in a reasonable quality. I assume this fiddliness is the reason why no one is actually doing the work. So your suggested process is good, but if no one does it (as has been the case), then we get into the situation we are in now. So: theory good, practice #FAIL. IF the wikibot can do the job, great; but I doubt it can do all the fiddly bits. I would love to be wrong. BTW, we get very little feedback through the wiki, so that is not really a problem IMO. It's the amount of work to put up well presented wiki pages. That's a lot less work than going the other way (wiki to ODT), though, for the user guides. --Jean --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
