[Dspace-general] Week 6: Documentation

[Dorothea Salo]

On Mon, Sep 29, 2008 at 8:28 AM, Dorothea Salo <dsalo at library.wisc.edu> wrote:

> When you face a DSpace difficulty, where is the first place you turn?
> The second? Third? When all else fails, where do you go?

It depends on the problem, honestly. Often, the problem is "I can't
remember the syntax of a command-line operation." In that case, I
usually know whether it's something I've documented on my blog, and if
I have, that's where I go. If not, I hit up the DSpace docs, which are
a 4 for this purpose -- not a 5 because they're a pain to scan and
search.

Sometimes the problem has to do with the incomprehensible DSpace
authorization and permissions system. I don't even BOTHER with the
DSpace documentation for this; it is a solid 1. I resolve these by
trial and error.

For design problems involving JSP and Manakin, I check the HOWTOs on
the wiki. For JSP, these are somewhere around a high 3 or low 4; for
Manakin, they're about a 2. The Manakin documentation, unfortunately,
is also a 2 for design problems. It's aimed more at people who want to
understand the underpinnings of the system than at the hapless souls
who want to do something with it. Comments in the Manakin stylesheets
are a 3; they often contain vital clues to resolving design problems.

Let me say this again, louder: doing a Manakin design that's any more
than a CSS refresh is a *hard development problem*, and there is
practically *no* documentation aimed at those of us interested in it.
I'm not quite ready to write the documentation I would want to see,
because some aspects of Manakin (notably making DRI and METS play
nicely together) still break my brain. (Though I think moving to a
call-template design pattern with a lot of with-params instead of
apply-templates might solve the specific problem I'm having. I need to
force myself over the scared-to-try hump before I'll know.) Ask me
again in six months.

The wiki is not an ideal solution, honestly. I wikified the
Donohue/Phillips/Salo customization guides a while ago; doing so was a
fair bit of work, it didn't turn out perfectly, and I freely admit I
haven't kept them up to date. I seriously doubt I'm the only person
who's created local documentation, but it sure looks as though I'm
nearly the only person putting it on the wiki. If we mean to continue
crowdsourcing our documentation, we need to acknowledge and accept
that people use the tools they use.

I want to give a shout out to the community, because a year or so ago,
asking the -tech or -devel mailing lists for help was somewhere around
a 2, and now I think it's a 4. We are doing a *lot* better at
resolving questions than we used to, and we should be proud of that.
The number, type, and repetitiveness of questions we get, however,
indicates pretty clearly that our documentation lacks a lot,
particularly for new DSpace sysadmins.

I also want to point out some documentation and training examples I
think worth following. The Fedora Commons tutorials
(<http://fedora-commons.info/resources/>) are absolutely brilliant; I
went through them last week, and while I'm still a little shaky on the
content-model architecture, I'm happy with my understanding of the
object model. We have nothing comparable in DSpace, although something
like that would be a beautiful thing to have on the DSpace-on-a-CD
distribution.

As for EPrints, it is so far ahead of DSpace
(<http://www.eprints.org/software/training/>) that as someone who's
done a little DSpace training, I'm *embarrassed*. I particularly like
the breakdown of concerns on the EPrints page
(enduser/config/customization).

Dorothea

-- 
Dorothea Salo                dsalo at library.wisc.edu
Digital Repository Librarian      AIM: mindsatuw
University of Wisconsin
Rm 218, Memorial Library
(608) 262-5493