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

[David Kelly]

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20110227/84e5fe56/attachment.html>