Improving the documentation process

[Karsten Wade]

On Mon, Feb 09, 2009 at 05:22:16PM +1000, Christopher Curran wrote:

> No one thinks a simpler system is good, or bad?

Here's the ironic part -- the system you describe is very much like
the system we have been using for the past few years.  (Close enough,
anyway.)

As I've mentioned before, the process pages are full of cruft and are
hard to understand for new and experienced contributors.  Improvement
needed.  I am an OK person to work on that, but also think someone a
bit newer might do a better job.  No foul for it being unclear as you
read it, right?[1]

I think the difference of opinion that we are balancing on is the idea
of using the wiki as a primary/initial authoring tool for some
documents.  Because of the 1000x more contributors to the wiki, it is
currently a better way to get the wider community involved in
documenting.  It doesn't mean we bow to the will of the wiki, but it
has to be a serious part of the equation.

One reason we have subtle variations is precisely because people such
as yourself come along and want to treat their upstream document in
their own way.  A team wants to work on a new document entirely in
DocBook XML, great!  A team wants to work in wiki first, then convert,
great!  OO.org then convert to DocBook XML, great!  For the most part,
you'll notice, DocBook is the integration point, even if it is not
always canonical.

In addition, some documents lend themselves to variations.  For
example, the User Guide is a good document for a larger group of new
contributors to collaborate on via the wiki.  It is worth starting
each new version back on the wiki.  At the end of the writing, the
conversion for each version to XML ends up teaching them more about
DocBook XML.  This is because the conversion from MediaWiki produces a
set of working XML files, and the conversion team is focused on inline
XML markup.  In the future, the team might choose to stay in XML,
great!

The release notes are a third variation.  At one time, we considered
the wiki canonical throughout the process, but that proved to be too
much of a PITA.  This last release, we made the XML on
fedorahosted.org/release-notes canonical after the conversion.
Because the content is 80% new for each release, we have gone back to
clean beat pages to author for each release to gain the collaboration
force multiplier.

Thanks - Karsten

[1] As a note, the original steps you wrote at the start of the thread
presume a bit of back knowledge.  It also compresses out the actual
processes involved in each of those content development methods.  For
me, I am at my most unclear when I start to write out al those
details.  I think that is part of why [[DocsProject/WorkFlow]] is so
unclear.

-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20090209/b65c258e/attachment.bin