<div><br></div><div>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.</div><div><br></div>
<div>My preferences when writing documentation:</div><div>1) Google docs</div><div>2) Word/open office</div><div>...</div><div>99) Manually entering octal values in a hex editor</div><div>...</div><div>9001) docbook</div>
<div><br></div><div>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:</div>
<div><br></div><div>$ google docs get --title "Userguide 0.92"</div><div><br></div><div><a href="http://code.google.com/p/googlecl/">http://code.google.com/p/googlecl/</a></div><div><br></div><div>I've installed it on my laptop and it seems to work well so far.</div>
<div><br></div><div>David</div><div><br></div><div><div class="gmail_quote">On Sat, Feb 26, 2011 at 4:26 PM, Michael Wilde <span dir="ltr"><<a href="mailto:wilde@mcs.anl.gov">wilde@mcs.anl.gov</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">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.<br>
<br>
1. Treat the Swift web as a standalone entity, whose backbone framework can be content- and version- managed outside of Swift SVN.<br>
<br>
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)<br>
<br>
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.<br>
<br>
a) Do the 3-4 pages we identified for 0.92 release<br>
b) Convert all such content on the SWFT wiki to this format as a first step.<br>
<br>
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.<br>
<br>
5. Decide on one of three strategies for SVN docs:<br>
<br>
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.<br>
<br>
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:<br>
- the tools are "just" python scripts<br>
- the format is very simple and amenable to production with plain text editors<br>
(and much easier on the eye for writing)<br>
- its got a much larger and growing user base and tool support than docbook<br>
<br>
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.<br>
<br>
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.<br>
<br>
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.<br>
<br>
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:<br>
<br>
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.<br>
<br>
Exp 3. See what improvements we could make in the docbook content editing and management process.<br>
<br>
What changes, if any, to this approach would people suggest?<br>
<br>
- Mike<br>
_______________________________________________<br>
Swift-devel mailing list<br>
<a href="mailto:Swift-devel@ci.uchicago.edu">Swift-devel@ci.uchicago.edu</a><br>
<a href="http://mail.ci.uchicago.edu/mailman/listinfo/swift-devel" target="_blank">http://mail.ci.uchicago.edu/mailman/listinfo/swift-devel</a><br>
</blockquote></div><br></div>