[Dspace-general] Documentation
Michele Kimpton
michele at dspace.org
Wed Oct 1 10:49:33 EDT 2008
Greetings DSpace community,
Just in case you may have missed it, I wanted to make sure the
community was aware of two newly published resources for documentation
and training and some upcoming plans. The first is a full suite of
courses put together by RSP in the UK. This set of materials is
professional, well done and comprehensive. You can find it on the
DSpace website under resources> training materials at http://www.dspace.org/index.php?option=com_content&task=view&id=604&Itemid=227
. You will find other select materials produced by the community
here as well that may be of value.
Also the DSpace documentation was updated and republished with the
release of 1.5.1 ( it has been changed significantly since the 1.5
publication). This manual is much richer and accurate in content,
through the help of many community members. The Foundation drove the
process of trying to get the manual as thorough and accurate as
possible. Brad McLean, our technical director, will be publishing an
email later in the week to describe the publication/editing process
moving forward to keep the content accurate and dynamic. The latest
manual can be found under software> documentation at
http://www.dspace.org/index.php?option=com_content&task=view&id=151&Itemid=116
The training documentation on Fedora and EPrints are professional
documents that were not put together by the community but were funded
by Moore Foundation money or JISC money to produce by professionals.
I wanted to make sure this was clear as it would be unrealistic to
expect the DSpace Community to have the same quality of documentation
without the same level of financial investment. That being said, I
hope if the Foundation is successful in raising sponsorship funds so
professional development of materials could be supported over time.
Until such time, we need to continue to improve upon the process and
participation of the community and the Foundation can provide support
and infrastructure to help in this process.
best, Michele
On Sep 29, 2008, at 12:03 PM, dspace-general-request at mit.edu wrote:
> Send Dspace-general mailing list submissions to
> dspace-general at mit.edu
>
> To subscribe or unsubscribe via the World Wide Web, visit
> http://mailman.mit.edu/mailman/listinfo/dspace-general
> or, via email, send a message with subject or body 'help' to
> dspace-general-request at mit.edu
>
> You can reach the person managing the list at
> dspace-general-owner at mit.edu
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Dspace-general digest..."
>
>
> Today's Topics:
>
> 1. Week 6: Documentation (Dorothea Salo)
> 2. Re: Week 6: Documentation (Dorothea Salo)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Mon, 29 Sep 2008 08:28:35 -0500
> From: "Dorothea Salo" <dsalo at library.wisc.edu>
> Subject: [Dspace-general] Week 6: Documentation
> To: DSpace <DSpace-tech at lists.sourceforge.net>, dspace
> <dspace-general at mit.edu>
> Message-ID:
> <356cf3980809290628i292d2701l14f725a97c6e80fd at mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8
>
> Greetings, DSpace community,
>
> My apologies for last week's discussion hiatus; I still had several
> showstopper bugs in Manakin themes and an uncomfortably close go-live
> date. The showstoppers are fixed (with many thanks to the community),
> and my headspace is just that much clearer.
>
> This week's topic is documentation, something the survey asked about
> previously.
>
> When you face a DSpace difficulty, where is the first place you turn?
> The second? Third? When all else fails, where do you go?
>
> On a scale of 1 to 5, where 1 is "never find anything useful" and 5 is
> "always solves my problem," how would you rate the resources you just
> listed? What would a 5 resource look like and contain?
>
> Finally, what would you be willing and able to contribute to DSpace
> documentation?
>
> I will facilitate a chat discussion of these questions this Wednesday
> 1 October at 11 am ET (10 am CT, 4 pm GMT) in the #dspace IRC channel
> on irc.freenode.net.
>
> Dorothea
>
> --
> Dorothea Salo dsalo at library.wisc.edu
> Digital Repository Librarian AIM: mindsatuw
> University of Wisconsin
> Rm 218, Memorial Library
> (608) 262-5493
>
>
> ------------------------------
>
> Message: 2
> Date: Mon, 29 Sep 2008 09:08:31 -0500
> From: "Dorothea Salo" <dsalo at library.wisc.edu>
> Subject: Re: [Dspace-general] Week 6: Documentation
> To: dspace <dspace-general at mit.edu>
> Message-ID:
> <356cf3980809290708x4cc23cft746b34f62d034d07 at mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8
>
> 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
>
>
> End of Dspace-general Digest, Vol 62, Issue 28
> **********************************************
More information about the Dspace-general
mailing list