[Swift-devel] Plan for managing Swift docs

[Sarah Kenny]

hi all, i started the documentation planning page here:
https://sites.google.com/site/swiftdevel/

i attempted to give everyone full access using
swift-research-group at googlegroups.com

please let me know if you're able to edit, etc.

~sk

On Tue, Mar 15, 2011 at 11:26 AM, Michael Wilde <wilde at mcs.anl.gov> wrote:

>
>
> ----- 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20110316/0ad446c0/attachment.html>