Improving the documentation process

[Christopher Curran]

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