GSoC - Target Practice

[Paul W. Frields]

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.
> 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.), 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 think DocBook XML is the only sane way to do this, yes.  Right now our
SCM is CVS but we are as flexible on that as any other part of Fedora.
If everyone decides tomorrow we're going git, then we'd move to it as
soon as practical (and someone more dev-savvy gave us recipes for doing
it 98% guaranteed not to break stuff).  The best idea for this would be,
I'd assume, genericizing a function that could getattr() or otherwise be
directed to use an appropriate SCM-specific function, to ensure long and
healthy code life.

> I don't want to program anything that we wont end up using. 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
> - 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?

Once ported to Plone, wiki pages should be either (1) expired/redirected
to the Plone site, or (2) made read-only and subsequently
generated/posted by Plone.

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

I think this is madness, plain and simple.  Plone will be just as easy
(or more so) for newbies to edit, using Kupu and styles you+we provide
that generate a substantial portion of the important XML tagging.  The
wiki simply cannot accommodate this without imposing large sets of
non-mnemonic tagging "rules" that either (1) scare off contributors even
more easily than DocBook XML if we insist on them, or (2) require
moderate to large increases of work from DocBook-savvy editors to check
and correct later.  With Kupu and styles, almost anyone can improve
tagging!

> * 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 guess I don't understand this part well enough to comment on it
meaningfully.  Seeing this in action may be a breakthrough for me.  I'm
planning on being at FUDCon 8 and the following hackfest, if that's any
help.

> * Where do we go from here? Automagic "this is all our documentation"
> DocBookXML generation?
> 
> Please, understand all of this is not point and click for me to setup...
> but it can be done. ;-)

Well understood.  Please continue to push back detailed questions, and
we will do as much as we can to help.  I'd like to keep ideas flowing
here on f-docs-l as much as possible to keep the community involved, or
at least aware, and I'm sure others feel the same.

-- 
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/20070613/7351a33a/attachment.sig>