[Swift-devel] Plan for managing Swift docs

Tue Mar 15 12:54:30 CDT 2011

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 

----- Original Message -----

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 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20110315/1ba81ad5/attachment.html>