GSoC - Target Practice

Sat Jun 16 18:24:15 UTC 2007

On Wed, 2007-06-13 at 13:25 -0600, Jonathan Steffan wrote:
> Hello,
> 
> 	I am now announcing my availability to take RFEs. We will basically be
> targeting Plone 3 which has a lot of the features we want to use as a
> documentation platform. Please, we need to start a nice task list for me
> so I can budget my time between all of the projects I have going.

Can you start with deriving a task list from here?

http://fedoraproject.org/wiki/SummerOfCode/2007/JonathanSteffan

Maybe just derive it into a new Tasks/ sub-page.

Plone is an important part of that solution-set, but only a step along
the way.

So, for example, when looking at the i18n features of Plone, we have to
decide if we are using them for just displaying l10nized content, or do
they have some value to use beyond that.  Otherwise, we're best off
sticking with using Plone as a tool on top of existing l10n efforts.

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

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

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

> 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

> - 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 tried to use the #REDIRECT feature for external (URI) linking, but it
doesn't work that way.  The idea I had was, once a document is pushed
from the Wiki as a draft, we could turn the old page into a redirect to
the new location.

To do that, we would need a way to detect document names for URL
creation, or create one according to guidelines.  Maybe part of the use
case/process includes a jump to an interstitial page (GatherFoo) for
gathering information for the next step:

Wiki => GatherFoo => Plone workflow
CVS => GatherFoo => Plone workflow
Kupu => Plone workflow

GatherFoo would pull together all unanswered questions -- what is the
final URL destination (maybe select or start from a drop down menu?),
which editor's queue to put it in, is this a test or a release (alpha,
beta, RC, GOLD, etc.)

> - Can we edit from both locations? (oh no... /me sees lots of work
> piling up)

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?

> * 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).  
  - Depending on the individual user, someone with sufficient rights
should be able to instantly publish a document from CVS
    - 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

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

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.

Good start? ;-D

- 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/20070616/01ffb436/attachment.sig>