[Swift-devel] A suggested web content strategy for Swift

[Michael Wilde]

David wrote:

> If we wanted to, I think it's possible to automate Google docs -> SVN.
> There is a set of utilities called google command line tools. They are
> written in python and allow you to do things like:
> 
> 
> $ google docs get --title "Userguide 0.92"
> 
> 
> http://code.google.com/p/googlecl/

This would be a big plus for making Google sites/docs usable as our document editor, without loosing the ability to do proper svn management.

Can the tools copy from Google to a textual format that can be svn'ed and then copy files back to an new online URL without loss of format?

Can you propose what a good svn-based management and release deployment process would be for say the Users Guide, Tutorial, and a future Reference Manual?

- Mike


----- Original Message -----
> Personally I find it easiest to write documentation by using Google
> docs. We used google docs in a software engineering class, and I found
> the collaboration abilities to be very useful.
> 
> 
> My preferences when writing documentation:
> 1) Google docs
> 2) Word/open office
> ...
> 99) Manually entering octal values in a hex editor
> ...
> 9001) docbook
> 
> 
> If we wanted to, I think it's possible to automate Google docs -> SVN.
> There is a set of utilities called google command line tools. They are
> written in python and allow you to do things like:
> 
> 
> $ google docs get --title "Userguide 0.92"
> 
> 
> http://code.google.com/p/googlecl/
> 
> 
> I've installed it on my laptop and it seems to work well so far.
> 
> 
> David
> 
> 
> 
> On Sat, Feb 26, 2011 at 4:26 PM, Michael Wilde < wilde at mcs.anl.gov >
> wrote:
> 
> 
> Condensing thoughts from many teams members (Sarah, Justin, Mihael,
> David, Ketan) and tying together various discussions on this topic,
> here's my suggestion on how to proceed.
> 
> 1. Treat the Swift web as a standalone entity, whose backbone
> framework can be content- and version- managed outside of Swift SVN.
> 
> 2. Treat Swift documents (User Guide, Tutorial, and eventual Reference
> Manual) as svn-managed part of trunk and each release branch, pushed
> to version-specific URLs and linked into the web backbone manually
> each time a new release appears (or eventually, automatically)
> 
> 3. Use a fast web content manager (Google sites or docs) to make
> preliminary versions of newly developed user content available fast;
> then migrate that content to the appropriate SVN-controlled document.
> 
> a) Do the 3-4 pages we identified for 0.92 release
> b) Convert all such content on the SWFT wiki to this format as a first
> step.
> 
> 4. Use Google Sites to gather and mock up the structure and content of
> a revised Swift web site that addresses the main new-user and
> user-community-growing needs.
> 
> 5. Decide on one of three strategies for SVN docs:
> 
> a) stay with docbook but clean up the format of the content (mostly
> indentation and tabbing issues) and conquer the problems of tool
> execution and the push-to-web process.
> 
> b) switch to Sphinx and reStructured text, ala the Python
> documentation framework. This will have its own tool and push issues,
> but is more likely to be easier on many counts:
> - the tools are "just" python scripts
> - the format is very simple and amenable to production with plain text
> editors
> (and much easier on the eye for writing)
> - its got a much larger and growing user base and tool support than
> docbook
> 
> c) use Google docs *iff* we can svn-manage the content loss-free in
> some text format in SVN. Then we use Google Documents simply as a
> ubiquitous wysiwyg editor but we push each revision back into SVN.
> This is less likely to be feasible but worth examining.
> 
> 6. Push hard to consolidate our web content and get to the point where
> we can first enlist Gail Pieper and others to review and improve the
> content.
> 
> 7. Then engage the Argonne/CI web team to help spruce up the look.
> They may suggest at that point that we move the site to Word Press,
> ala most of the Argonne and CI production sites, including the Globus
> Online site.
> 
> So I *think* that we are on exactly the right track with respect to
> most of these points. I suggest we do some fast, lightweight
> experiments to decide on how we want to manage the document content.
> One to three experiments (in the order below) might help guide us
> here:
> 
> Exp 1. Try using Google docs (or perhaps sites) as an editing tool for
> the user guide. See if we can save content to text, push to svn, push
> to web (and pdf) from there, and repeat the editing cycle. I would be
> OK if we had to sacrifice the page-per-chapter html format for now.
> 
> Exp 3. See what improvements we could make in the docbook content
> editing and management process.
> 
> What changes, if any, to this approach would people suggest?
> 
> - Mike
> _______________________________________________
> Swift-devel mailing list
> Swift-devel at ci.uchicago.edu
> http://mail.ci.uchicago.edu/mailman/listinfo/swift-devel

-- 
Michael Wilde
Computation Institute, University of Chicago
Mathematics and Computer Science Division
Argonne National Laboratory