[Swift-devel] Plan for managing Swift docs

[Michael Wilde]

Sarah, All, this looks very good, and comprehensive.

You might need to break it into chunks with some kind of rough timetable.

A few notes below.

----- Original Message -----
> hi all, here's a list of tasks, based on mike's email, that ketan and
> i discussed and think can be fairly easily assigned as action items.
> we determined which ones we think we can/should work on and i'm taking
> a stab at assigning the others. feel free to edit as you see fit and
> then ideally we can get them into bugzilla.
> 
> Google docs/sites for Swift User doc
> 
> 1 KETAN move all our current doc to google
> 2 KETAN determine method for save/review/push to live site (google’s
> java app for dumping to file)
> 3 JUSTIN keeping the docs in sync with the trunk and releases. Ability
> to associate (and get) the docs for any release branch
> 
> 4 KETAN content writing and management guide to encourage writing and
> maintain quality and conventions
> 5 KETAN clear/uniform look and feel with ability to change the style
> throughout, when needed (example:
> https://sites.google.com/a/brain-connectivity-toolbox.net/bct/Home )
> 6 KETAN code testing: how to ensure that code examples in the docs are
> correct?
> 7 DAVID maintenance of external links (eg Google vs svn)

??? vs svn or vs ci.uchicago?

> 8 DAVID ability to (automatically) render PDF’s, standalone HTML, and
> text

Did you discuss how to decide between Google Sites vs Docs for eg the User Guide?

> 9 SKENNY ability to index terms

Low prio, right? Perhaps for now search-within-site is more important than index?

> 10 SKENNY automated system for tracking and publishing changes

Lets make sure we keep it as simple as we can. Maybe this item is done simply by using good conventions for develop-review-launch?

> 11 SKENNY Define document structure & substructure: Site, Quickstart,
> Tutorial, User Guide, Cookbook (should eventually go into user guide),
> and Case Studies.
> 
> 12 SKENNY migrate all of the SWFT wiki content (including docbooks
> which should go in user doc). (eventually decomission).

Can be done gradually.

> 13 MIHAEL determine timeline for transition

??? transition of all the above? Seems an odd role for Mihael? I'd have thought you'd do a timeline for this, as Mihael seems least involved in much of these tasks?

> 14 SKENNY make URL more transparent/CI-branded

Then maybe I didnt understand 7 above. Note, Google Sites has some info on this, and CI support can perhaps help. Also, its low prio.

> 15 DAVID site style improvements (eg logo stripe; page width , etc)
> 16 KETAN determine best editor: google sites vs google docs

OK, cool. Bears on my comment to 8 above (rendering).

I see lots of nice examples in Google Docs documentation that suggest nice page-numbered PDFs are possible from Docs "documents". I think there may be some css involved in this.

> 
> 17 KETAN table of contents management.
> 18 DAVID how to track/address
> comments for public revision control? (eg, posting to svn log?
> Automated tool?)

Seems Sites has public comment boxes. Not sure we want these unless they can be moderated.

> 19 SKENNY determine site, page, and doc naming convetions
> 20 DAVID Use of Google Groups for access control

Sounds great. A good thing to do next is to filter out the essential from the lower prios.

Nice!

- Mike


> ~sk
> 
> 
> On Tue, Mar 8, 2011 at 2:21 PM, Michael Wilde < wilde at mcs.anl.gov >
> wrote:
> 
> 
> 
> 
> > as far as the other points in the email...i'm wondering if we want
> > to
> > discuss via skype and try to get it down to a concrete list and
> > divide
> > up the work? given how many varying issues we've touched on here i'd
> > feel a little better if we could get them into action items that we
> > can put into bugzilla as enhancements and assign them...does this
> > seem
> > reasonable? i'm worried back and forth via email might be a little
> > less effective (though i'm happy to put all my comments in email if
> > others prefer that).
> 
> Im at a meeting all this week and cant do much email or voice calls.
> 
> I think, Sarah, that you and Ketan meeting and proposing a plan back
> to the group would be great.
> 
> Maybe after you meet, a bit of email before you turn the plan into
> bugzilla trackable items would be good. Then using bugz for this (and
> more of our work tracking) would be great.
> 
> I'll pipe in as time permits.
> 
> - Mike

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