help define our workflow, other notes

Karsten Wade kwade at redhat.com
Sat Jul 14 23:18:51 UTC 2007


On Sat, 2007-07-14 at 13:49 -0400, Paul W. Frields wrote:
> >         ## 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.

That is a fairly good analogy.

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

Well, not really the flexibility for normal cases.  That is, a document
can be visible at various stages in its workflow, but whether fresh
changes are shown lives depends on which stage it is and what it has to
go through to be live.

The idea is, the closer you get to a final, formal publishing (to
docs.fp.o/document-name/), the more restrictive each succeeding workflow
step is.  Early draft flows easily, but once you start to e.g. get
things being translated, it is more difficult (in terms of process, not
tools) to make an edit.

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

+1

This particular question around translators might be a bit different.
By the time a translator has found an error, the content is in the
'stable' workflow state, and resolution needs to be handled by a more
experienced team member (editor, writer) with sufficient permissions.  A
decision has to be made (via bugzilla, mailing list) and a new POT
pushed (if needed), then some social work has to be done (alert
translators via mailing list, in addition to any workflow alerts they
receive.)  In some cases, the error report was on a mailing list, where
the solution gets worked out, and the thread needs to be closed.

So, there is going to be complexity and 'harder' here because of the
number of people affected.  But I do agree that the tooling shouldn't be
difficult to match -- i.e., don't make an editor drop to the CLI to
handle this.  BUT -- the editor should be able to do this from the CLI
(cvs + Jon's daemon).  And there should be sufficient
checks-and-balances to ensure other contributors are not walked on by
the changes. :)

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

This is essentially the autobuild server I was asking about.  It can be
hacked on to do all sorts of stuff we might find useful.  For example,
I'd like RelEng to be able to trigger a build and staging of all they
need for packages that have content originating in /cvs/docs (such as
the release notes, but could be parts of /usr/share/doc/, etc.).

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

Detected one time and searched for in multiple instances?

http://translate.fedoraproject.org/search

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

This is interesting to ponder.  We'll have to first decide how we are
going from XHTML => XML, then test what that does with the various
styles.  I reckon we can do a fair bit with CSS classes.  Might need a
bit of custom work in between (XHTML => XML w/ classes => XML) to
interpret the classes into the specific XML elements.  Or, you know,
maybe it will have been done by someone already?

- Karsten
-- 
   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/20070714/cdd04701/attachment.sig>


More information about the fedora-docs-list mailing list