...
This effort was organized on the Help Files and Documentation Process Redesign page.
Titanpad: http://titanpad.com/wzm95ulYwR
Please sign in to the Titanpad.
Participants
- Name a moderator and a minute-taker
...
1. Introductions/Expectations/Skills/Availability of participants
2. Current Status
See final item on Help Files and Documentation Process Redesign page.
3. Define goals
- Scope (redistributable KB or wiki, prioritized list of docs needed)
- Exploration of different levels of documentation for different audiences
- SDK documentation for developers
- Official policy for developers' institutions' submittal of documentation
...
6. Define structure of this group
Dump of minutes from TitanPad
Documentation Conference Call
10 December 2010
Participants
- Robin Hill, University of Wyoming
- Jonathan Bolte, Indiana University
- Matt Clare (alternate: Giulia Forsythe), Brock University
- Mathieu Plourde, Delaware
- Karen Kral, Delaware
- Whitten Smart, Texas State
- Elizabeth Venstra, Indiana
- Kara Stiles, rSmart
- Jim Mezzanotte, rSmart
- Trisha Gordon, University of Virginia
- Lorie Stolarchuk, University of Windsor
- Vern Bloomfield, Columbia University
- Seth Theriault, Columbia University
- Clay Fenlason
- Jon Hays, UC Berkeley
- Sean Keesler, Three Canoes
Sakai Knowledge Base
JB: Limited by lack of partners. Should be on a Sakai server. Sakai Wiki thought to be better, but never took off. Continuous development effort too much for intermittent contributors. But now could a new opportunity.
RH: We need an incremental level of commitment, perhaps.
Meeting at Correct Time
Eliz.: Sakai KB pulled from Indiana repository (maintained as part of QA process). Content here, S. Marquard pulls from there when necessary for Help files, archiving old files.
Seth: Indiana content committed automatically to code base, archives part of official code base.
Jonathan B: Indiana content for Sakai obtained through web services (REST), transformed with XSLT. Data in XML, so any institution could do same. Content is kept current, old versions not maintained at that address. Responsible for core tools, but interest is focused on Indiana tools, of course.
http://confluence.sakaiproject.org/display/ESUP/Help+Files+and+Documentation+Process+Redesign
Example from Stanford (Samigo):
- Tool has been developed by people that are long gone
- History of the coding has been lost
- Documentation has been updated, but adhoc
- Stanford documentation is way better
Many projects on Confluence are obsolete
Some difficulties in documenting Portfolios
Mathieu: Many facets to the documentation issue. Questions of procedure, accessibility, levels of need, all apply. This group can decide goals.
Sean: What about the possibility for adapting others' institutions docs? Motivation, from Pepperdine, for this renewed effort.
Campus needs differ beyond just changing identifiers. Many institutions like Michigan have many materials that supplement Help Files. And some institutions need to remove refs to unused tools. And to change permissions and so forth. And clarify and streamline the style. (Or maybe elaborate.)
Eliz: We can be more vigilant.
Seth: Clay and I have been concerned about docs, but lacked focus. We want to improve OOTB docs. Some Help files written by developers; not the best approach. Would be best guide for fostering improvement of future docs, Sakai 3/OAE.
Lorie S: Can Help files be tagged with exact Sakai code version?
Clay: Can be both better and simpler by eschewing tool-centered organization. Maybe overviews would be a better way.
Jonathan: Support requires both kinds. We could track hits and do analytics on which docs get lots of views. As for version meta-data, no version number attached to files when pulled, but some files include version number in title.
Eliz: Version is accurate only to "2.x" not "2.x.x"
Clay: Smaller versions shouldn't have feature changes.
Lorie: How can we use REST and compare versions?
Jonathan: You can use a client tool to compare the documents. Would hope to have a tool that does that in Sakai.
EV: https://kb.iu.edu/data/arhw.html gives some information about SOAP & REST, but it's written for people who know more than me!
Robin: We could have a QA process for documentation, but it's not something that can be automated. We need eyeballs
Jonathan: Documentation for tools that are used at IU is vetted, not the other ones
Lorie: About to have student volunteers to have them go through the doc at Windsor.
Robin: Sustainability is problematic in such an effort, as in QA in general.
Clay: School are already heavily involed in documentation, coordination is what needs to happen. But their need can be pitched as the incentive.
Jonathan: Making the documentation customized is another process that goes beyond collecting.
There are no free collaboration tool that's available right now, IU is bbuilding one for Kuali.
UI pulls the KB stuff in a UI Confluence, that can be customized
We could use InCommon to connect to a central authorative KB
wiki.iu.edu
Seth: There's content, and there's the delivery mechanism.
Clay: Fixing the documentation is like fixing a bug, could use Jira, but should use the lists (especially the Dev list, but the End-user could be used as well).
Guilia: How did the Wiki doc import work? (Into Windsor Help files)
Lorie: The problem is updating to new versions.
Guilia: Is there resistance to use MediaWiki?
Seth: What the Sakai community uses is Confluence. The expertise is there, but we all have preferred tools. Delivery mechanisms vary, and the configuration flexibility is deliberate. But a custom method must take delivery into account. Best to improve current method.
High interest is great!
Sean: Consider problem of coalescing documents from MediaWiki.
Lorie : Signing off. Happy holidays folks!!
4 efforts:
- Documentation push
- Aggregate the best documentation from all around the world
- Contributing mechanism and coordination of same
- Delivery mechanism
- Export in different formats (Plain HTML, Confluence, MediaWiki, Drupal, etc.)
- Style guide and documentation models and paradigms
Clay: This group should try to get involved with the 2.9 release to change the model for the OOTB help
Seth: There is a schedule for the 2.8 release. Our content should be ready by then? TCC handles technical concerns and coordination.
TCC Confluence space: http://confluence.sakaiproject.org/display/TCC
2.8 schedule: http://confluence.sakaiproject.org/display/REL/Sakai+2.8+Release+Schedule
"Help deadline" was 11/2/2010
Eliz: Note that Help Tool not the same as the Help files. The Help Tool presents the content.
Jon H: Help Tools presents a mix of perspectives, in a flat (2-level) format. Could be better. Would be nice to present more pedagogical solutions.
Eliz: Indiana Help Tool has deeper hierarchy. https://oncourse.iu.edu/portal
EV: IU's help tool is not great, but maybe a bit better than OOTB Sakai?
Or not.
Seth: New or improved content for 2.8 probably needs to be done and committed by mid-late January.
Jon: We need a place to get started in making the help files better. Conflucence?
EV: I need changes marked. If the only way to do that in Confluence is to compare first and last versions, so be it. But editorial markings would be better.
Alan to organize follow-up meeting in January.
Seth: This group needs a fearless leader to interact with the TCC, QA, Rel Mgmt, IU KB, etc.. <-- ACTION ITEM