[Swift-devel] Plan for managing Swift docs

[Michael Wilde]

----- Original Message -----
> right, so, my list of tasks was an attempt at distilling mike's
> initial email into action items and was meant as a rough first pass
> that i was hoping others would contribute to or help to
> clarify/refine...

Exactly - and it was an excellent start! I think this is going real well, and Im just trying to keep it moving and do some tuning.

> it seems that i didn't fully understand/correctly
> interpret some of the items mike had in mind.

No problem - the list is long and writing docs is a non-trivial effort that like code takes much discussion and coordination.  Plus what's in my mind is just a starting point and certainly needs much clarification, discussion and improvement.

> mike, it sounds like you're saying it's best to move that list to a
> shared doc so that everyone can edit (?)

Right - edit, track, revise the plan, etc.

> if so i can do that...are we
> thinking i should create a google doc for this or a page on the site?

Either. Its the kind of thing we would have previously kept in the SWFT wiki. We can either to that, or, as I think better, migrate the SWFT wiki to a fresh SWFT site that we use for the exact same purpose. But do a better separation between internal group process docs and user-facing prelim docs.

Also, we need I think 2 such internal wikis - one for swift-devel as an open source project, and one for our team, for inwards-facing issues related to our jobs at Argonne and CI.  So lets make a swift-devel web (or a sub dir for this on the main swift swift) and a SWFT web for private group coordination.

But all that said, the *main* thing I was asking for in the prior message was to put on the planning page the info that Swift writers need to know where to write what, and how it goes form draft to review to live: mainly just site names and structure for now.

Thanks,

Mike

> otherwise i can try to reply to the inline comments. however, in
> either case i may need some help clarifying what was initially
> intended :)
> 
> 
> On Tue, Mar 15, 2011 at 10:54 AM, Michael Wilde < wilde at mcs.anl.gov >
> wrote:
> 
> 
> 
> 
> Sounds good - but related to this, something very important: can you
> create as soon as possible a page we can all share that specifies the
> (evolving) doc conventions, the most important part of which is the
> names of the sites to use for various stages of the process (ie:
> development, review, live) and what page naming strategy and structure
> to use.
> 
> 
> Ive lost track of what is going where and dont know where to turn to
> find things, nor where I can edit prototypes or contribute to docs in
> progress.
> 
> 
> Ketan tells me that he doesnt seem to have the right access to edit /
> create in the development site(s)?
> 
> 
> And he too doesnt know the answers to what is where - so we need more
> coordination and communication to get things going so that everyone
> can contribute - which is the major reason we are moving to online doc
> tools.
> 
> 
> Keep in mind that we can use email to *discuss* things, but decisions
> and spec info need to be in a well known, easy to find place that we
> all can share.
> 
> 
> Lastly, this really needs to all stay on swift-devel so that we can
> coordinate as a team, especially since many people dont work on Swift
> every day.
> 
> 
> 
> 
> Thanks,
> 
> 
> Mike
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> i have not done so...if no one else (and you haven't already) you want
> to go ahead and create it and share that info?
> 
> ~sk
> 
> 
> On Fri, Mar 11, 2011 at 2:44 PM, David Kelly < dk0966 at cs.ship.edu >
> wrote:
> 
> 
> 
> Has anyone already created a generic swift google account? If so,
> could they please send me the username and password for the purpose of
> setting up automation via google command line tools?
> 
> 
> Thanks,
> David
> 
> 
> 
> 
> 
> On Thu, Mar 10, 2011 at 2:35 AM, Michael Wilde < wilde at mcs.anl.gov >
> wrote:
> 
> 
> 
> 
> 
> 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
> 
> _______________________________________________
> 
> 
> 
> 
> Swift-devel mailing list
> Swift-devel at ci.uchicago.edu
> http://mail.ci.uchicago.edu/mailman/listinfo/swift-devel
> 
> 
> 
> 
> 
> --
> 
> Michael Wilde
> Computation Institute, University of Chicago
> Mathematics and Computer Science Division
> Argonne National Laboratory

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