GSoC - Target Practice

[Paul W. Frields]

On Sat, 2007-06-16 at 11:24 -0700, Karsten Wade wrote:
> Similar with writing, except Plone has the *potential* of replacing the
> Wiki with the nice Kupu editor.  To make it work with our systems, Plone
> needs to keep that XHTML somewhere where:
> 
> * Either it sits in CVS directly and we modify our docs toolchain to
> pull POT/push PO from XHTML, or
> * The XHTML is converted to XML, then built back to XHTML for publishing

The second bullet is the one I was specifically hoping for.  I don't
like the idea of adapting our toolchain for a less portable document
model; I'd rather Plone took care of turning the XML into XHTML for
publishing.  So here's my take on how things would work:

1.  A clueless n00b writer can write using Kupu.  The document on Plone
is XHTML.  The Kupu styles allow tagging, but we can assume the n00b
won't do it.  That's fine because...

2.  A clueful editor comes along and uses the Kupu styles to "tag" the
document.  For instance, he turns some XHTML that just reads:
    ...use the Anaconda installer...
into:
    ...use the <span class="application">Anaconda</span> installer...

3.  When a document is updated, Plone transforms that document into real
DocBook XML:
    ....use the <application>Anaconda</application> installer...

4.  I suspect "workflows" are ways to allow humans to approve changes or
do other things to documents.  Preferably, then, a human is allowed to
look over the proposed changes to the document and, if approved, the
human stamps them for a SCM (CVS for now) commit.

Does this make sense and look achievable?  This is not the be-all,
end-all for the entire solution, but it's a big part of what we're
worried about.  We want n00b writers to be able to write as easily as
they do on the wiki, but with the added benefit of allowing
"half-skilled" editors to do tagging.  Fully skilled editors can do
really hard work however they like.

Plone would need to watch the SCM to make sure it is not generating
conflicts, in case I check in a document to CVS while a n00b is changing
the content on Plone.  I think things like hourly polls are probably
simpler but worse than having Plone "read" or trigger on SCM commit
messages to know when it needs to update something.

> > Basically, I would like to as the docs team what they would like to see.
> > Details such as final format (i.e. DocBookXML), VCS backend (i.e. svn,
> > cvs, git, etc.),
> 
> After writing the above, I realize we pretty have to keep it all in the
> same VCS as our other docs, which means CVS.

+10.

> > and *where* we can edit the documents once they hit the
> > documentation platform would help me get a better idea of what we are up
> > to. I don't want to program anything that we wont end up using. 
> 
> Once content has e.g. left the Wiki, maybe we want it to be a one-way
> street?  That is, it gets converted to XML and Plone handles it now.  If
> you need to edit with a WYSIWYG approach, use Kupu.

Yes, one-way street is sane.  In a beautiful, shiny world, we'd bring
the whole wiki into Plone and have steering committees deciding on what
basis any content appears as "published" in their official namespaces.
This might well be "wide open" for many groups to encourage freshness.
Individual contributors could use their personal spaces for drafts
however desired, of course.

> > Also,
> > and example document workflow would be awesome. Example:
> > 
> > * User creates wiki object 1 on the wiki
> > * People edit it for a few days/weeks and then it starts to become a
> > usable document
> > * Someone with access; Admin publishes the wiki object as a draft into
> > the documentation platform
> 
> Here is a dump.  Please pull these and put them on a
> SoC/2007/JonathanSteffan/Workflows or /UseCases page.
> 
> 1. Users write content in $EDITOR; when ready, they "Push Draft":
>  1.1 If in the Wiki, they have a new action that we push upstream to
> Moin, "Push Draft to External Toolchain", which is configurable;
> basically, choosing the option causes a script to run, so our script
> isn't in Moin, just the generic trigger.  Our script then:
>    1.1.1 Uses Moin to convert to XML
>    1.1.2 Puts that in CVS (may need to gather some module info from the
> user)
>    1.1.3 Builds the document to XHTML
>    1.1.4 Pushes the XHTML into the start of a Plone workflow queue
>  1.2 If in Plone, "Push Draft" puts the XHTML into the start of a Plone
> workflow queue
>  1.3 If in CVS/XML directly, have a 'make cms-draft' target that:
>    1.3.1 Builds the doc
>    1.3.2 Pushes it Plone at the start of a workflow queue

The above piece that I wrote may be subsume or be subsumed by this -- if
Plone watched for SCM commits, quite a bit of this could be automated.
It doesn't need to necessarily parse entire commit messages, just
trigger on them to update its own XHTML content as required.

> > - What happens to the content that *was* on the wiki.. can it still be
> > edited? Is it read only, pulling its data from the doc platform?
> 
> Paul had some thoughts here ...
> 
> My thinking is that any editing we are pushing from is likely to come
> from Docs/Drafts/, so it's clear it is not a canonical source.
> 
> For something like Docs/Beats/, the Wiki source remains the source of
> content.  However, once a draft is pushed, that draft goes into CVS and
> is tagged with a test/release-specific label.  In that situation, the
> Wiki is a sort of pre-HEAD.
> 
> We can review the Wiki-usage; maybe the Beats can be maintained via
> Plone instead.

I think Beats, Drafts, and anything else can and should be maintained
via Plone.  Easier, web-based account management should make it a very
simple operation to add people to FAS and various authorized groups.
Rather than giving out CVS access willy-nilly, we can simply add people
to access groups on Plone.

> Part of me doesn't want to limit editing in the Wiki source (i.e., not
> turn it read-only.)  However, this seems like a path to further insanity
> -- dead-end unmaintained pages, etc.  Better to limit some Wiki freedom
> for the overall good?

Yes, it's become clear from the amount of cruft accumulated on the wiki
that "everybody have at it!" is not a winning strategy in the long term.
It raises exponentially the chances that people are going to find bad,
outdated, and wrong information, which has been one of our guiding
lights for Things Not To Do.  Certainly we don't want to dictate to
other subprojects what they do, but moving editing of Things That Matter
out of the wiki and over to Plone permanently seems pretty rational to
me.

> > * The document goes through it's life-cycle in the documentation
> > platform. This is a very flexible system as we can define a very
> > strict/granular workflow (states, transitions, etc) for individual
> > objects... primarily document content types.
> 
> I understand what you mean from a CMS standpoint.  We can version
> documents, specify an expiration date (where appropriate), and have the
> documents go through many states:
> 
> Document_Foo_Lifecycle (Draft => Editor (approve or push back) =>
> Published Draft; Update Draft => Editor => Publish Updated Draft; Loop
> last until satisfied; Expire Drafts; Final => Editor => Publish Final)
> 
> What do you mean by "document content types"?
> 
> > * Where do we go from here? Automagic "this is all our documentation"
> > DocBookXML generation?
> 
> Some automagic we'd like to see in the doc publishing platform:
> 
> * Autobuild of HEAD for all documents (listed in a special file
> somewhere?) as "docs rawhide"; could be done into Plone or just as
> static builds off docs.fp.o
> 
> * As alluded to above, some additions to the toolchain, new make targets
> (make cms-draft, make cms-publish).  

(Redundant point: might be unnecessary depending on whether Plone can be
trained to watch for changes.)

>   - Depending on the individual user, someone with sufficient rights
> should be able to instantly publish a document from CVS

Ahh, this is sensible and cool, I hadn't thought hard enough there!

>     - Use case: Editor fixes a small typo and wants to publish as a new
> point release; after fixing the typo and saving, the editor types 'make
> cms-publish', which i) builds, ii) checks-in to CVS, iii) drops the
> document into Plone as "publish immediately to the configured location".
>   - 'make cms-newdraft' does something similar, except it republishes
> the document into the special state of "new draft of previously
> published draft."
> 
> Some other ideas:
> 
> * Ability to make all workflows happen quickly/near-instantly, by admin
> fiat and using one or more "Build Now" instead of the default "Schedule
> Build."
>   - In general, we don't want people to be able to kick off instant,
> overriding builds; they should be queued, run by cron/schedule, and
> automatically niced; but it should be possible for either an editor,
> publisher, admin, or maybe anyone to push a build near-instantly

Yeah, the "scheduled build" idea is an idiom we should probably try to
avoid in any future endeavor.  It uses a lot of time and disk activity
that is largely unnecessary and my interfere with real usage.  Much
better to have something external *trigger* the requirement to build or
publish (or whatever), so it only gets done when needed; cf. IRQs or
D-Bus messages.

> > Please, understand all of this is not point and click for me to setup...
> > but it can be done. ;-)
> 
> Heh, wouldn't be much of a coding project if it were point and click.

We *might* have done it ourselves if so... You know, in our "free
time."  :-D

> Let's get all these ideas and others you gather from IRC and the Wiki,
> put them on a page as a #'d list, and sort them by priority.  That gives
> us a chance to identify all the dependencies, esp. the ones that are off
> your personal radar/control.  We may decide to push some features out
> until after the summer.  One thing we *must* do is plan the future, so
> you aren't the go-to guy for this always.  Ideally, we can build up a
> bit of a project around this; there will be other people who use the
> same tools (SCM + XML + Plone + Moin).  Let's make sure that building a
> community around our solution is one of the tasks on the list.  Getting
> upstream acceptance for any changes to Plone or Moin is another
> must-have.

Hope my ramblings here are not muddying the waters.  If any of this
exceeds scope, please take it down as a "do-later" so we can still track
progress as the project proceeds after the deadlines have been met.

-- 
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/20070616/0cbbdf20/attachment.sig>