On 9/30/2010 04:31, 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.
Why Protecting Wiki Pages is (IMHO) a Bad Idea:
Recently, a helpful user made a change to the Math Guide (which I
reverted). After a long investigation, I documented a localization
feature; for details, see the Feedback folder for Math Guide on OOA.
(The German-speaking user very helpfully made some of the necessary
changes on the German Wiki version.)
We should not expect casual users to jump through all the hoops
necessary to file an issue, or fix an OOA ODT doc. But, fix the wiki?
That they can do. And they do.
A bot or script to check all the pages in a wiki chapter for edits, new
talk pages, &c., would be very helpful for collecting these
contributions. This would work in conjunction with whatever
version-marking method we decide on, to give only subsequent 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 two "big fiddles" (processes which require an inordinate amount of
work by the editor) that I see are "pages" and "pictures".
We could include some kind of wiki-page markers (hidden paragraphs,
possibly bookmarks) in the ODTs, which would greatly simplify wiki
maintenance, but at the expense of complicating ODT maintenance.
"Pictures" is what I'm working on. I can (I think) automate everything
but the picture upload. If I generate a folder full of files like
"010433_001.png", "010433_002.png", &c., the editor will still have to
type all those unlovely names into the upload window, even though I can
generate a list of them. The "multiple file upload" wiki feature is
helpful, but not helpful enough. Can a bot do uploads?
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.
--
/tj/
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
