[Bf-docboard] Plans for the Future

[Ted Schundler]

> Wiki looks actually *much* better online. I don't know about printable, this
> is something to check. And also the possibility of a big archive to check
> offline is vital. These are the points we must  evaluate :)

DocBook can look however you want it to online. I think you guys maybe
don't really understand it. DocBook is just a way of marking up data.
It's not a program, or something to install. Though you can install
translation tools, to convert docbook to some more useful to the
users. I offered a month ago or so to work on improved XSLT style
sheets to make the online documentation more presentable, but didn't
get a single reply. (And won't have time for anything extensive until
August or so)

The PHP or MySQL online documentation are based on DocBook, and both
allow user comments on the pages and are formatted very nicely.
Of course all PHP and MySQL users are inherently technical types, and
learning a few XML tags is not something dauunting preventing them
from contributing.
Though, really you don't need to _learn_ anything if you've used
XML/HTML before - just take something that exists and copy how that
does it. And you don't need any software. (Though it does help to
avoid accidental unbalanced tags)


I think DocBook is particularly nice for managing a decent size
documentation project with multiple contributors. It inherently forces
some standardization, and works nicely with CVS. And not every
contributor NEEDs to know DocBook. If someone wants to contribute a
section, they can just send their contribution however they like, and
then an editor puts it in the actual documentation. Content
submissions should ideally be reviewed by an editor anyway.
In my limited experience w/ actual printed publications, the content
authors always just used Word. No need for them to even learn
PageMaker. They submit their work to an editor. And then further down
the line someone else was responsible for putting it in PageMaker.

OpenOffice I think is a bad idea. Can it even support books made from
multiple files and cross references between them? It seems like it
would be potentially just as much of a hassle of not more in terms of
managing it as something coherent. But if anyone has had luck with the
OO.org DocBook XSLT filters, that might be worth looking into for
making things more managable for content author producing DocBoook
content.

FrameMaker would be excellent, but that's obviously out of the
question unless someone wants to donate a bunch of licenses.

Wikis are probably the next best choice to DocBook of what has been
suggested, but in my experience they tend to be a bit of a pain to
practically navigate due to the loose design. But it is easy to
contribute.  In general where I've seen it used for software
documentation it seems to be used as a way of avoiding the work
involved in more organizated documentation by letting the whoever
contribute whatever they want.
Are there any cases of successful software documention using Wikis?

Does the docboard have defined roles like Editor in Cheif, section
editors, etc.? (Sorry, I'm relatively new to the BF documentation
efforts) Maybe setting up titles and defined roles world help more
than using different technologies. Editors have CVS access. Everyone
else works through them. Editors have roles - i.e. managing sections,
or consistency, or screen shots, etc.



Ted Schundler

PS: Regarding generating and uploading content, you can't just
re-generate a chapter. It's not possible because all cross references
need to be preserved.It can't know apriori what will be affected.
However for moving data, you might want to look into rsync or
something similar to only update files that changed if upload time is
a problem.