Karsten Wade wrote:
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.)
No, no it's not. The present system has several manual stages and
several superfluous stages. That entire CVS to PHP to old docbook system
is a prime example of why there is nothing even remotely alike about
what I proposed and what currently exists.
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]
Sure, which is why I advocate chopping it back. I think the first step
should be to draw a flow diagram using inkscape or the gimp and see
exactly what the process is versus what we want. Every process page
needs a flow diagram so all people working on the project can clearly
define where they sit in the development life cycle.
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.
I wasn't saying we drop the wiki or not acknowledge it's presence. The
key difference in what I am saying is writing books is not writing a
wiki. A wiki cannot replace author collaboration, it is the wrong tool.
No author, past or present has penned their tome on a wiki. That's not
to say that the wiki is not important just that it should not be
considered THE place for writing books.
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.
I have no issues with how a team works. My issue is with the complexity
of the publishing method. Right now it is quite hard to go from Docbook
to hosted content. That is where we need the most revision of present
practices. Regardless of the complexity involved it should be a one step
push. Documentation projects should be pre-approved to push updates to
the hosted content. Documentation projects need to be treated more as
stand alone projects which publish to fedora docs project rather than
work in subjugation to.
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!
Nothing in my proposal excluded such a team from working that way.
Again, what I am arguing for is simpler publishing.
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.
This is low level detail to distract from what I am saying.
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.
Also RE: Murray
The CMS is Yet Another Markup and Yet Another step in an abysmally long
chain. What we need is an automated tool to publish work from
documentation projects.
The entire argument about making editing easier is stupid. Editing is
hard. The generic open source method for edits and corrections is filing
bugs. This works just as well for documentation projects as it does for
kernels. I know the impulse of software development is to reinvent the
wheel and call it something new but it is wrong. If we continue to think
that using a CMS will fix anything we are just deluding ourselves. What
we need is a publishing tool. Nothing else will fix our present problems
other than a publishing tool.
Chris
--
fedora-docs-list mailing list
fedora-docs-list@xxxxxxxxxx
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
