Child pages
  • 2010-12-10 End-User Documentation Meeting
Skip to end of metadata
Go to start of metadata

This meeting will be held on Friday, December 10, 2010, from 3:00 to 4:00 p.m., EST (12:00 noon to 1:00 p.m., PST)
Call-in info:
Telephone: +1 812 856 7060
Conference Code: 22386#
PIN: 72524#

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

Agenda

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

4. Timeframe

5. Success stories, other products available?

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