[Swift-devel] Plan for managing Swift docs

[Mihael Hategan]

I agree with the fact that documentation is important at this point. I
also agree that we should try new things. It will allow us to make a
more educated decision in the future. I may have suspicions about what's
the right (or wrong) way to go, but those suspicions may be wrong. So I
support your plan.

Mihael

On Sun, 2011-03-06 at 12:18 -0600, Michael Wilde 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