Child pages
  • Notes from documentation BOF session at Sakai 2012 conference
Skip to end of metadata
Go to start of metadata


  • Elizabeth Venstra, Indiana University (note-taker)
  • Harold Hale, Antioch
  • Stephen Marquard, University of Cape Town
  • Chris Strauber, Tufts
  • Gloria Hardman, Yale
  • Danielle Thacker, VT
  • Barb Kerns, Bradley U.
  • Matt Clare, Brock U.
  • Sam Ottenhoff, Longsight
  • Bryan Holladay, Longsight
  • Jonathan Bolte, Indiana
  • Seth Theriault, Columbia (TCC member)

Elizabeth Venstra took the following notes of the discussion portion of the BOF session.  To understand them, you need to know that as of now (June 2012), many (but not all) of the help files in the out-of-the-box Sakai installation are maintained in the IU Knowledge Base (KB) repository, and then brought into the Sakai release by synchronization scripts set up by Stephen at Cape Town.


  • I know I didn't capture everything, and I'm not sure what I did capture is more important than what I didn't.
  • I may have captured some comments inaccurately.  (Please correct the notes if you feel that I mistook what you said.)
  • Ideas are generally the opinion of the speaker, not necessarily the opinion of the whole room.  I captured some of who said what, but sometimes I didn't capture who said things.  While I think that the spaces below are generally between different speakers, that's not guaranteed to be 100% accurate.

That said–the overall sense of the meeting was agreement on this basic path forward: Exploring a process that removes IU from the process, and allows the community to make edits in a collaborative space, and then write the changes directly to trunk.


Sakai documentation BOF 2012


[intros, what people are interested in]

People don’t look at just script (as opposed to screenshots)

Diff. between student and faculty info



There’s nothing role-based (Alan)

Navigation back to home page is difficult


Wouldn’t want it to overwrite what I’ve already done to customize

Seth: hearing that there needs to be more flexibility

Help today is more flexible than it used to be, but hasn’t changed in a long time

The way the help tool functions needs to evolve again

Seth: time to cut IU out 

(Editorial note: Elizabeth and Jonathan, from the IU KB, are just fine with this idea!)

Now to get the flexibility you want, you have to mimic the [XML?] structure



Help is downstream of deployment and development

Versioning.  Tools not standalone completely . . .

Even if we take the IU KB out of the equation . . .

Variation across sites makes it a thorny problem

Between KB and Sakai SVN—mostly about constantly shifting pages


Jonathan: More flexibility you need in an application, more modular your management of content, the better you can manage . . . but sometimes too complex for schools to mess with

Don’t know that you’ll ever get to single format or repository for all the help

Could be a lot more work in common


Matt: developers haven’t kept up with help


Sam: Drupal thing put together last year

Imported from current help

Anyone can go in, rich-text editor

Piece didn’t do: saving back structure, SVN  but could do that—could write directly to trunk

Take out the technical piece

Could add a process w/editors and vetting, but don’t think about that until you have that problem

Would remove the process of having to get a developer to run scripts

Would overwrite whatever’s there


We’re not overrun by rogue editors


Variation in style not that big a deal—people who care will probably write their own help anyway


How would one handle screenshots?


Sam: I would want everything to be automated

For a generic screenshot, Selenium remote control allows screenshot

Theoretically, could branch for institutions, where Selenium runs against your institution

(would take a lot of time)


It’s not just the skin that’s different—buttons can be different


Matt: student-focused vs. instructor-focused text more important than spending a lot of time on screenshots


Tutorial tool avoids screenshot problem because it points to actual thing in the interface


Challenge: making sure help content for that system rolls out with that system

Freer system would allow this to be easier


Content authoring and update for Sakai release addressed by all this, but doesn’t address actual end-user interface

EDIA better for this . . .

English to Dutch.  New help tool, role-based system

But what about people with multiple roles?

Claim they used all open source and contributed the tool


Jonathan: do people collect statistics on what students actually need?

Jonathan: could reduce amount of documentation if thought of it as support, not documentation—don’t document everything

Alan: it’s the faculty actually looking things up


Sam: will resurrect Drupal thing from last year

Willing to do about a week’s worth of work on it

CLE team perspective: difficult to get massive rewrite of help tool

Could get in small tweaks, e.g., respects your stealthing

Not going to be anyone in the community willing to rewrite help


Someone needs to reach out to EDIA

Are you willing to make this into a core tool and help out the community, is what we’re asking . . .

Uses Solr (?)


Help Files and Documentation Process Redesign (parent page)

  • No labels