On Jan 24, 2006, at 8:08 PM, Ted Husted wrote:
On 1/24/06, Dave Johnson <[EMAIL PROTECTED]> wrote:
Personally, I think the wiki is great for collaborative document
development -- things like proposals, FAQ files and up-to-the minute
docs such as release notes. But for formal documents like the user
guide and installation guide, I much prefer using a real word
processing system with a user-friendly interface and the ability to
save to PDF and HTML.
8< snip
A binary word processing format does not promote collaboration. It
promotes an environment where one or maybe two people do all the work.
Don't agree.
I realize that right now Dave is doing all or most of the work on the
documentation.
** BUT THAT IS A BAD THING!!!! **
Definitely do agree.
The ASF does *not* want any aspect of any project to be dependant on a
sole individual. Every member of the PPMC needs to be in the loop on
everything the podling project does, and every member has to be ready
to step up and do what needs to be done should other people be
unavailable.
OK, let's have a show of hands: How many members of the PPMC have a
*clue* of what changes we made to the User Guide last week?
Anybody can find out by using the Compare Document feature of Open
Office to compare the two versions in SVN, it shows every single diff
and even shows diffs within a single line. Try it.
I have a clue because I submitted the "patch". But I really don't know
what Dave applied and what Dave didn't apply. Only Dave knows. One
person. And that is bad. Very, Very Bad.
My suggestion is that we (meaning I) move the documentation to XML
that can be rendered by Forrest, or Maven, or just plain Ant, which is
what most other projects do. The changelog for the XML commits can be
read by human beings, and then everyone is able to know exactly what
changes.
Are you also volunteering to maintain the document and update it in
step with our monthly releases after it's been converted?
You're right Ted, I don't to carry the entire burden of documentation
but using a XML format does not increase the likelihood of getting
additional resources to help with writing. Most tech writers that
I've worked with prefer using a word processor like Framemaker or
Word or Open Office and not editing raw XML with Emacs or messing
with a build script, so I contend that using Open Document format
would actually increase our chances to getting help with documentation.
Collaboration is very important and its the main reason Roller wants
to move to Apache, but aren't we supposed to be finding ways for
everybody to help out, not just developers? We want to get tech
writers, testers, trainers and project managers (hi Linda) helping
too. I don't think mandating raw XML formats for all documentation is
not necessarily the best way to do that.
- Dave
