[Swift-devel] Plan for managing Swift docs

Tue Mar 15 13:16:08 CDT 2011

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...it seems that
i didn't fully understand/correctly interpret some of the items mike had in
mind.

mike, it sounds like you're saying it's best to move that list to a shared
doc so that everyone can edit (?) if so i can do that...are we thinking i
should create a google doc for this or a page on the site? 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20110315/2ead9a07/attachment.html>