help define our workflow, other notes

Fri Jul 13 22:05:25 UTC 2007

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

Translation is currently slated to go through the new translation
system. All translations are pulled from CVS, none will be pushed back
into CVS via plone... currently at least.

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

PDF rendering could be done via plone gears. It would be rendering for a
specific language and will be for the latest render in the ZODB (plone).

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

This should be up for more discussion when in Draft. Some times it is
just a small trivial edit and the change will be pushed to CVS when we
move to "stable".

>         
>         Not formal doc space == Wiki, personal Plone space,
>         fedorapeople.org
>         
>         Formal doc space == XML builds into HTML hosted via a CMS
>         (Plone)
> 
> == More Notes ==
> 
> Staging == the ability to edit a new version of a document while the old
> version stays "live" and viewable to the public.
> 
> Free drafting happens in the personal Plone space -- default
> workflow[2], no constraints, show others, peer review, etc.
> 
> When a writer is first ready for a review/editor, they use the default
> workflow[2] to put it in an editor's queue for review.  The editor(s)
> and writer(s) can use this to go back and forth until they are satisfied
> they have a document ready for publication.  
> 
> The default workflow state of 'published' is a good starting point for a
> document that is ready to go into CVS and the formal Fedora Docs
> workflow[1].  Content could also come in from other sources, such as the
> Wiki (through CVS), from CVS, or from a Plone document.
> 
> Once in the workflow, a document moves from draft to stable.  Stable is
> where translations occur.  Anywhere along the way, a document can be
> rendered and committed to CVS.
> 
> Staging works here by letting us keep a live version from updating
> without it first being translated.  This keeps documents from being out
> of sync.
> 
> Remember, this is all for our formal, published documents.  This is
> where content goes after we do lots of collaboration on writing it via
> our favorite $editor program, which could be Plone or it could be vi or
> it could be the Wiki.  Docs/Beats => release notes is the model we are
> following.
> 
> [1] 
> == Fedora Docs Custom Workflow ==
> 
>   'draft' - new content
>   'commit' - committed to CVS
>   'stable' - ready for translation
>   'render' - offload rendering of XML in all $lang
>   'published' - grab render and publish
> 
> More details coming, based on answers to our questions.
> 
> [2]
> == Default Workflow ==
> 
> Default roles:
>   owner - owns the document (wrote it)
>   reviewer - reviews and edits the document
>   manager - full permissions to the documents of the people they manage
> 
> The default workflow looks like this:
>  
>   'private' (only owner can edit and see) [and managers]
>   'public draft' (everyone can see, owner can edit) [managers can always
> do whatever]
>   'submitted' (reviewers can edit, owner can not, everyone can view)
>   'published' (everyone can see)
>   'revoked' [from submitted] gives edit rights back to owner
>   'rejected' [from submitted] moves back so owner can edit, with a
> notice of rejection and why
>   ... and a few other things
>   most of that will be customized to some degree

I've attached the new draft diagram of what our workflow might come
close to looking like. Expect more revisions but this should help clue
people into the whole "workflow" system more. The latest worflow draft
is "workflow2.png" ... I've attached old work so everyone can see.

Jonathan Steffan
daMaestro
-------------- next part --------------
A non-text attachment was scrubbed...
Name: moin2plone.png
Type: image/png
Size: 142125 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070713/c598ab98/attachment.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: workflow.png
Type: image/png
Size: 99080 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070713/c598ab98/attachment-0001.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: workflow2.png
Type: image/png
Size: 63192 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070713/c598ab98/attachment-0002.png>