[Dspace-general] Week 6: Documentation

[Shane Beers]

Sorry for the delay in my response to this one:

When I face a difficulty, I most frequently turn to direct contact  
with a dspace developer I know, or you, Dorothea. My main issues stem  
from a modification not working correctly or something similar, so  
documentation rarely covers my problem.

I'm dreadfully afraid of even making a move to a 1.5.1/Manakin-based  
interface simply because it seems like documentation and guides are  
dreadfully sparse. Additionally, I'm pretty certain the embargo  
modification we added on will not function in 1.5.X, and ultimately  
the obstacles we face here aren't technical in the least - so my work  
is better spent in marketing and promotion.

I also try to use the mailing lists to get help with problems.  
Unfortunately the majority of my questions must be woefully  
unsolvable, because I haven't received help that solved them most of  
the time.

Shane

--
Shane Beers
Digital Repository Services Librarian
George Mason University
sbeers at gmu.edu
http://mars.gmu.edu
703-993-3742



On Sep 29, 2008, at 10:08 AM, Dorothea Salo wrote:

> 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
> _______________________________________________
> Dspace-general mailing list
> Dspace-general at mit.edu
> http://mailman.mit.edu/mailman/listinfo/dspace-general