Improving the documentation process

[Paul W. Frields]

On Tue, Feb 10, 2009 at 11:07:16AM +1000, Christopher Curran wrote:
> 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.

This is a pretty good idea -- it helped when I was working with John
Poelstra on the Feature process pages to see the workflow for the
process he had in mind.

[...snip...]
> 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.
[...snip...]
> 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.

I'd swear that you sound like someone who's getting ready to sell us
an automated tool to publish to hosting.  I'm not saying I for one
would turn it down.  But would you care to just go ahead and put it on
the table so we can look at it and figure out the next steps?

> 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.

In other words, you want the Fedora Docs Project to do things the same
way that you do them in Red Hat Engineering Services.  That's
understandable and a valid PoV.  But if we have to do that to get your
positive input and all of our volunteers disappear, that's a pretty
high price to pay.

My hope is that we can have both, but to do that you need to go past
the idea stage, as have the folks who are working with the Zikula
crew.  Put the tool on the table (or some level of detail that you
envision).  Work with the Infrastructure team to get a test instance
on one of the publictest servers, so we can weigh one workflow against
the other.  Based on what you're saying, it should be pretty clear if
the CMS really isn't helping as much as a publishing tool.

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20090210/4fd85ca4/attachment.sig>