help define our workflow, other notes

[Paul W. Frields]

On Fri, 2007-07-13 at 13:04 -0700, Karsten Wade wrote:
> I captured the below questions and answers during a chat with Jon
> Steffan (daMaestro) today.  Jon is building our next generation
> publishing system.  It will make it very easy for _all_ of us to write,
> edit, translate, and publish using our favorite tools.  It will be 1000x
> better than our current publication method on docs.fedoraproject.org.
> 
> To open, I'll answer Jon's questions and my answers to him, then give
> the rest of everything so you can put in your answers and thoughts and
> questions.
> 
> == Jon's Questions ==
> 
> Jon is working on some diagrams, and his pretty pictures depend on our
> answers.
> 
> 1) assuming we *can* do full staging (ie .. what has been 
> rendered stays live until another render is issued); what is 
> the default state for the edit? draft?
> 
>         ## KW - I think a default of 'draft' makes sense; that way we
>         don't lock the document for editing until we really mean it.

+1

> 2) at the published state... do we *force* a stage (eg.. you 
> can't edit the published.. (well.. you *can* but you really 	
> just edit a clone that is a staged version)
> 
>         ## Clarification -- staging in this case means, changes to a
>         document are not shown live until the workflow on the new staged
>         version is complete

So it's kind of like a private branch that gets merged back to (or
replaces) the live version, if I get your drift.

>         ## KW - Yes, I think so.  As long as an admin can force an
>         update to content via some reasonable method for the rare
>         occasions (defacing, security risk, data risk, etc.), I think it
>         is reasonable to keep a document published until it has passed
>         through a QA and translation stage.

This gives us the flexibility of "right away publishing" from wikiland
but with better possibilities for l10n, PDF, etc.?  OK, I'm down with
that.

> 3) at draft, i assume all members can edit
> 
>         ## KW - Yes.  We want all members of Fedora Docs to be able to
>         edit in this workflow.

+1

> 4) at stable, i assume only key members can edit... and this 
> is where we go to translations
> 
>         ## KW - This makes sense.  Translators find mistakes or have
>         questions/clarifications for the original; an editor or original
>         owner needs to be able to fix those and push the content back
>         for translation (generate a new POT, alert translators with open
>         PO files, whatever.)  How much of this can be done through
>         Plone?  Through CVS?

The more we can do through Plone, the easier it will be for non-techies
to help with documentation.  That's a major blocker for our subproject
right now -- I suspect there are people out there who can correct
grammar and write good standard English, but who are frightened of doing
CVS because they think they might irreparably break something.  (A silly
or at least misplaced fear, but you have to respect the fact that they
care.)  So if they can do this with a pleasant, or at least
comprehensible, web interface, that's a win in my book.

> 5) "rendering" ... aka making all languages available (that 
> we have translations for at least) is staged and the 
> external rendering engine (some simple python xmlrpc daemon 
> that handles heavy lifting and security sensitive stuff) is 
> what actually does the push into the zodb (plone content) 
> for the live version
> we can render whenever we want
> 
>         ## KW - We cooked up this idea the other day on IRC, talking
>         with other Infrastructure folks.  This lets us off-load riskier
>         and more intensive operations to back-end services.  Front-end
>         Plone doesn't have to deal with committing to CVS or rendering
>         XML to HTML and PDF.

Yes, we certainly don't want Plone to become unresponsive every time the
CVS server is busy. :-)  I could see being able to email people results,
such as a PDF document, might be useful or desirable some day.

> 6) does *every* edit go back into CVS.. or do we want to 
> have inner plone staging with another state that is "commit" 
> ... so we have to exclusively commit back to CVS
> 
>         ## KW - once a document is in our custom workflow, it should
>         have all edits go to CVS.  For example, a writer or
>         editor/reviewer needs to be able to open the document as a
>         direct file in their $editor.  All edits have to be synced to
>         the same control management, once it is in formal document
>         space.
>         
>         Not formal doc space == Wiki, personal Plone space,
>         fedorapeople.org
>         
>         Formal doc space == XML builds into HTML hosted via a CMS
>         (Plone)

Right.  Part of the reason we want this is for good interaction with
Dimitris' DL work, where fixes can be detected visually by L10N'ers...
or by people who like detecting automagically against
fedora-docs-commits.  This does mean we have to get the Kupu-fu right,
or at least to a point where people like Karsten, me, Dimitris, John, et
al., can add styles to Kupu as needed to support all elements we use in
DocBook XML.

[...snip...]

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
      Fedora Project:  http://fedoraproject.org/wiki/PaulWFrields
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070714/7f86dc93/attachment.sig>