help define our workflow, other notes

[Karsten Wade]

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?

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.

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)

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

-- 
   Karsten Wade, 108 Editor       ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- 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/20070713/f71aa276/attachment.sig>