[Swift-devel] Plan for managing Swift docs

Tue Mar 8 09:42:36 CST 2011

Mike,

The plan looks very good. My comments and reactions below:

1. "M: code testing: how to ensure that code examples in the docs are
correct?  (M because we can do   this manually, and will always need to, to
some extent)"
 This should be the Highest priority at all costs. I have seen users come
again and again in search of code snippets, templates, examples to copy and
paste into their own environments. What we want to do here is to make sure
the users do not encounter any kind of error as far as we can. Ideally the
first error a user encounters should be at a point of no return for her (in
a lighter sense). Most users are not very patient and will tend to jump into
code right away after (or even before) first skimming through the text. We
want to make sure the code behaves nice to them.

2. Scripts are dry and kind of black and white and classy in the world of
visual and graphical workflows. I would say let's not make our documents so.
I am not saying to be funky but might we adopt a lighter style of
documentation! For instance using direct and active speech among other
elements of writing.

That is all I have to say at the moment.

Mike,
I am working on OSG Swift + Coaster experiments on CI nodes and will soon
start documenting them in the cookbook.

Best Regards,

Ketan

On Sun, Mar 6, 2011 at 12:18 PM, Michael Wilde <wilde at mcs.anl.gov> wrote:

> Hi All,
>
> Here's my proposal for Swift documentation. Please comment. We'll discuss
> this for a few days, make changes people feel are necessary, and then go
> with it and see how it works. I want to nail this down by this Fri Mar 11 if
> not sooner.
>
> Im proposing after a lot of thought and analysis that we *use Google tools*
> for the next 6 months to aggressively grow and improve our documentation;
> then we assess whether to stay with Google or consider going back to a
> markup-language-based approach.
>
> Barring strong feedback that "this wont work" its the direction I've decide
> to go in.
>
> Below are first the motivations and requirements that Ive based this
> recommendation on. After that are the elements that I thing we need to work
> into a plan.
>
> Justin, Sarah, Mihael, Keatan, David - this email is long but intended
> primarily for you. Sarah, David and Ketan, in particular, you should read
> this throughly and comment, as you will need to be the prime movers to get
> this going.
>
> *** Motivation
>
> The plan is based on two principles:
>
> - More comprehensive and useful documentation is the highest current
> priority for making Swift successful.
>
> - We need so much documentation work now (relative to our team size and
> available time) that *ease of creating and improving the content* and
> getting it to users should be given higher priority (for some period) than
> the cost or effectiveness of maintaining the content.
>
> *** High level Plan
>
> Based on these driving factors, I'm proposing this:
>
> - we move *all* our site and documents to Google for the next 6 months
>
> - for 6 months we work hard on improving the scope and effectiveness of the
> documentation
>
> - after 6 months, we evaluate the process and the results, and decide if we
> stay with Google or a similar online content management system, or we revert
> back to an svn-controlled markup process. If we revert, we select a markup
> language and toolchain based on an evaluation, and we absorb the cost of
> pushing the content back into markup language at that time.
>
>
> *** Requirements
>
> Here are the requirements I feel our documentation approach needs to
> address, and my view of their priorities.
>
> --- HIGH
>
> H: environment for content writing that encourages writing and continuous
> and collaborative improvement. (a good process for preview, multiple
> editors, comments, improvement)
>
> H: easy enough to make doc fixes so that fixes get made as soon as we spot
> problems that impede our users (or us)
>
> H: keeping the docs in sync with the trunk and releases. Ability to
> associate (and get) the docs for any release branch
>
> H: reasonable and easy page saving/reviewing/copying/releasing process
> (ideally easy to automate)
>
> H: a content writing and management guide to encourage writing and maintain
> quality and conventions
>
>
> --- Medium
>
> M: ability to review documents and changes as they evolve so that people
> can make improvements aggressively, knowing their changes will be notified
> to and reviewed by the community (both developers and users) for quality
> assurance.
>
> M: nice clean crisp look that is both aesthetic and readable
>
> M: doc style should stay uniform when many people write and edit
>
> M: ability to change the style throughout, when needed - ideally from a
> small number of style definitions
>
> M: code testing: how to ensure that code examples in the docs are correct?
>  (M because we can do this manually, and will always need to, to some
> extent)
>
> M: If we post documents from multiple sources (eg Google vs svn) we need to
> be able to maintain reasonable linkages between them that wont break.
>
> M: Page navigation within the doc set should be pleasant and effective for
> the user, and use good web principles. Page naming should be reasonable.
>
> --- low
>
> L: multiple high-quality renderings: as PDFs, standalone HTML, and text.
> This will be more important later, but is not at the moment.
>
> L: style definitions that anyone can improve
>
> L: ability to get the docs for any *trunk* revision.
>
> L: ability to render HTML as single page or a page hierarchy (higher prio
> as doc set grows)
>
> L: index terms: can we make an index?
>
> L: interactive viewing capabilities with highlighting ala DiveIntoPython
>
> L: we should track and publish for both us and our users a list of changes
> to both the software and the documentation (maybe M?)
>
> ---
>
>
> *** Detailed plan elements
>
> We need to develop a plan. Here are some elements it needs to address, and
> some specific issues related to Google use that we need to decide on (which
> will take some experimentation and testing).
>
> Sarah, Im hoping you can take these on (as youve already gotten a great
> headstart on Google evaluation), but lets make it a team-wide shared effort.
> Using Google should facilitate that.
>
> o Determine document structure.  Site, Quickstart, Tutorial, User Guide,
> Cookbook, and Case Studies,  for now is what I think we need.  Roughly in
> that priority order. Where Cookbook is things that should go into the User
> Guide eventually. For each of those we should next outline the substructure.
> How/where can we maintain such an outline?  Can it be simply the page
> structure of the "development" site?
>
> o Determine document style: headers, section numbering, colors and
> emphasis, paragraph styles. I feel that the Userguide format established by
> Ben is a great starting point. I have no desire to change it much for now.
> Eventually it can be made a bit crisper and perhaps more consistent.
>
> o Move the content we have now into this structure and style.  Move all
> end-user docs out of the SWFT wiki. (In fact, lets eventually move that wiki
> entirely into google and decommission it).
>
> o Enhance, specifically, the tutorial, and integrate the user-driven
> elements of the cookbook into the docset.
>
> *** Open issues (many!):
>
> These are in no particular order. A nextstep is to walk through these and
> make reommendations and decisions.
>
> ---
>
> (Note related to style: Sarah, the more I looked at the brain-mapping site
> you sent, the more I like it and see the possibilities here.  Can you
> determine how they did some of the things they do? Very nice clean look;
> very readable text styles.)
>
> determine doc style elements and how to enforce.  How to provide a
> swift-specific style drop-down for editing.
>
> timing and steps for the transition
>
> Things we can do to make the URL more transparent and CI-branded?
> How to make it look like our URL is same as now? Or at least swift-branded?
>
> site style improvements (eg logo stripe; page width (min? fixed?)
>
> automation of pdf production? Quality of PDF?
>
> indexing? (low prio)
>
> searching extensively *within* the site - higher prio
>
> google sites vs google docs? Push docs into the site?  Docs better for
> maintaining a style?  Better for printing?
>
> how to do and maintain graphical figures.
>
> where to keep templates for uniformity (swift writers guide)
>
> how to do backups?
>
> table of contents management.
>
> link management conventions (both within and outside of site)
>
> how to track comments for public revision control? (eg, posting to svn
> log?)
>
> style for reviewer comments? (both internal and user-based)
> facility for user comments and process for addressing?
>
> what site, page, and doc naming should we use?
>
> can we and should we use google more as an editor but route revisions into
> - automation tool ala the CL tools David pointed out to the list
>
> Can we get good unified search within the site? (that stays within the
> site)
>
> Use of Google Groups for access control: didnt work for Swift buti is
> working for ExM : not sure why.
>
> Ive asked Ketan to start writing and moving pages from the Swift Wiki to
> the Google Site "cookbook" area. Sarah, Ketan, can you make a structure for
> adding and maintaining the "cookbook" pages?  The main cookbooks Im thinking
> of at the moment is (1) a guide for the various coaster configs and (2) a
> guide for OSG users: how to get their certs and start running Swift on OSG
> sites using the new scripts we are working on.
>
> Like I said up front: comments welcome. But barring feedback that "this
> wont work" its the direction I've decide to go in.
>
> - Mike
>
>
> --
> Michael Wilde
> Computation Institute, University of Chicago
> Mathematics and Computer Science Division
> Argonne National Laboratory
>
> _______________________________________________
> 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/20110308/925606ba/attachment.html>