[Swift-devel] Plan for managing Swift docs

[Sarah Kenny]

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)
8 DAVID ability to (automatically) render PDF’s, standalone HTML, and text
9 SKENNY ability to index terms
10 SKENNY automated system for tracking and publishing changes

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).
13 MIHAEL determine timeline for transition

14 SKENNY make URL more transparent/CI-branded
15 DAVID site style improvements (eg logo stripe; page width , etc)
16 KETAN determine best editor: google sites vs google docs

17 KETAN table of contents management.
18 DAVID how to track/address comments for public revision control? (eg,
posting to svn log? Automated tool?)
19 SKENNY determine site, page, and doc naming convetions
20 DAVID Use of Google Groups for access control

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