Docs CMS ideas

[Nathan Thomas]

On 24/06/10 22:20, Karsten Wade wrote:
> While I've been waiting to see how the Zikula deployment went with
> Fedora Insight, we've finally seen a better update to
> docs.fedoraproject.org by using the native Publican site building
> tools.  I've waited to push forward with a CMS solution for Fedora
> Docs until we had a working solution to design against.
>
> While Publican gives us a way to build a nicely organized tree of
> content, it doesn't give other capabilities.  I don't know of any
> plans to include this sort of thing in Publican natively:
>
> * Ability to trigger (re)builds from source repositories via a webUI.
>
> * Workflow control, either by group (writers, editors, publishers), or
>   specific roles like that but per document (I can write this one, I
>   can edit yours, and I can push hers to publish after you edit it.)
>
> * WYSIWYG editor for DocBook XML from source repository.
>
> Basically, we still have very high barriers to move from "edit stuff
> on the wiki" to "manage a full guide on DocBook XML."  The main
> purpose for a CMS is to get the ability to publish and tweak
> docs.fedoraproject.org out of the hands of a very few, very busy
> people, and in to the hands of just about anyone that this team wants
> to authorize to do work there.
>
> Talking in the meeting yesterday, I threw out some ideas around this
> and agreed to bring those here.  I'm still interested in helping drive
> a CMS-like project for Docs.
>
> So I'll throw out a proposal to get us started.  This proposal exists
> partially because of our commitment to using Publican to publish.
> Another option is to use Publican only to generate documents, which
> are then loaded and versioned in a CMS e.g. Zikula or Drupal.  Working
> under this other option would be more like the CMS experience others
> have -- you either work in the native editor, or you upload documents
> you created elsewhere.
>
> == Docs CMS ==
>
> === Terms ===
>
>   * Publican is a command-line toolchain for building books as HTML,
>     PDF, Epub, Text, etc. and publishing them to a static website with
>     a navigation sidebar.  It uses books written in DocBook XML that
>     exist as installable RPM packages.
>
>   * Beacon is a wysiwyg, webUI editor that has been extended to
>     support DocBook XML editing.
>
>   * Fedora Hosted (fh.o) is a hosting solution that is the source
>     repository for Fedora Docs.  Books primarily use Subversion or git
>     as source control manager (SCM).
>
>   * WebUI is a generic term for the web user interface that we have to
>     write or configure to wrap around and perform certain functions
>     for this CMS.  For example, it can present a button to a person
>     with publishing privileges, when pressed triggers of a Publican
>     build on the backend.  This webUI could be custom code written in
>     Python and TurboGears, or it could be Drupal with a few custom
>     modules.
>
>   * A reader has the ability to read the website anonymously.  No
>     credentials are required.
>
>   * A writer belongs to a 'doc-writers' group and also belong to the
>     group associated with each document, e.g. 'gitinstall-guide'.
>     Being in the 'doc-writers' group is a prerequisite that exposes
>     the Beacon editor function.
>
>   * An editor is the same as a writer, performing a different role in
>     the process.
>
>   * A publisher is a member of the 'doc-publishers' group, which gives
>     the permission to trigger special functions in the webUI - build a
>     doc, rebuild a doc, install a doc package, etc.
>
> === WebUI architecture ===
>
> Functions:
>   0. Read
>   1. Write/edit
>   2. Publish
>
> 0. Read
>    a. Publican produces pages and navigation at docs.fp.org.
>       i. These pages are static and not wrapped by the webUI.
>    b. Readers use Publican's navigation to read guides.
>
> 1. Write/edit
>    a. Writer clicks "Check out document for editing" (this is NOT a
>       locking mechanism.)
>       i. Clicking check out triggers a 'git clone' of the document
>       	 repo.
>       ii. The cloned git repo is then branched locally to the webUI
>       	  server, for example 'git branch quaid-20100224-UUID' with a 
> 	  short, sequential UUID such as 'AA00'.
>       iii. Beacon is then opened using the local file check out of the
>       	   XML.
>       iv. Beacon saves work only in the files in the cloned repo.  An
>       	  added functionality could trigger 'git commit' on save, but
>    	  this might cause too many commits without a log message.
>       v. The writer's training includes knowing to commit on a regular
>       	 basis, in a granular fashion, when one or more edit+saves
>    	 makes a good bundle for a commit.  Clicking on "Commit
>    	 changes" opens a log summary window, then a 'git commit -m
>    	 "$dump_from_log_summary_window" is done on the local repo.
>       vi. A writer's session should persist.  When the writer returns
>       	  and still has local changes committed but not pushed to the
>    	  master git repo, the writer is offered those files to
>    	  continue work on, or to checkout a different document.
>       vii. When the writer is done with the writing session, the
>       	   writer clicks a "Check in document to main repository".
>    	   This triggers a 'git push' to the master repository.
>
> 2. Publish
>    a. Publisher selects a document and version from a
>       dropdown/checklist menu.
>       i. This list is generated from installed packages on docs.fp.o,
>          information extracted using 'rpm' commands.
>    b. Publisher clicks "Rebuild and publish document."
>       i. A koji scratchbuild is triggered, which grabs the latest
>          source from the upstream repository and builds a package.
>       ii. When the build is done, the package is installed from koji
>       	  using yum.
>    c. Publisher adds a new document to the publish list.
>       i. Document must exist as package in koji already.
>       ii. Publisher uses a Moksha widget to identify the meta-package
>       	  OR a specific package name and version are supplied
>    	  manually.
>       iii. Package is installed on docs.fedoraproject.org.
>       iv. Cached list of installed packages is refreshed to update
>       	  document and version dropdown/checklist menus.
>
> <eof>
>
> - Karsten
>   
I don't have the technical know-how to comment on the details of
Karsten's suggestion, however as a relatively new contributor of limited
technical abilities (arguably the kind of user we are aiming to attract
with this) I have one or two thoughts:

1. It seems from Karsten's description that there are two things going
on here: a) a system to make it easier for new contributors to write and
edit documents (cloning repos, editing the files, pushing the edits back
to the repos), and b) a system to make it easier to publish completed
documents to the web. A web CMS might be able to tick both of these
boxes - or it might be more appropriate (and less work) to use a
separate tool for each.
 
2. Any user wanting to get involved in the Docs Project is going to have
to learn new skills, new ways of thinking and working - and this is a
good thing. However, if the learning curve is too steep, or even appears
so to a potential new contributor, they might be put off. So I guess
anything we can do to take advantage of new contributors' existing
skills and experience could make the learning process easier. A lot of
new contributors might not have had previous experience in using
command-line tools to build marked-up documents from remote repositories
- but they might have used a simple web CMS to publish their blog
articles. A familiar working environment could go a long way to reducing
the trepidation of learning new skills.

Just my two pence!

Nathan