I thought I should write something since I've been the person working
on the DSpace 1.6
documentation. I've written documentation before for other software
products, albeit
commercial library ILS, but still documentation.
Upon volunteering as the "Document Gardener" for DSpace 1.6 release, I
took it upon
myself to evaluate what was there and what needed to be done and what
should be done.
I also needed to acclimatize myself to the tools used for generating
the documentation.
Here's some salient observations concerning the manual:
1. It needed to be updated to reflect the changes since version
1.3.2. There were some
remaining text that pointed to 1.3.2 version and how the system
behaved and or operated.
2. Nomenclature. Some of the nomenclature used was foreign to users,
but not to a programmer.
That was addressed as well.
3. Re-organization. There was major re-organization performed for
this next release.
4 Enhancement. Our current documentation has been enhanced a wee
bit. What is still
missing, and was missing was the end user documentation. I'm
currently working on that.
(Any help is welcomed!)
5. Docbook xml knowledge. This is the area that seems to be the hot
topic of discussion.
While docbook.xml **was** foreign to me, I made it my job to find
everything I could about it.
It was enlightening to say the least.
This is not some fly-by-night standard. Docbook has been around since
1991 and in 1998
moved to SGML Open consortium which is now OASIS. It is formally
defined by a RELAX NG
schema and integrated with SChematron rules. Supporting this is W3C
XML Schema and
DTD.
Marking up documentation in Docbook XML is able to produce HTML, XHMLT
EPUB, PDF, man pages,
HTML Help and now Eclipse Help Center documentation.
Editing can be done in <Oxygen/> XML Editor's Author mode (GUI),
Altova Spy, and other GUI
editors, one can use XML editors too.
Compiling of the docbook into PDF and HTML can be accomplished using
FOP (free), DSSSL (Free),
WEP (Commercial) and other commercial software. I've used FOP and WEP.
What I didn't know and many people do not know is that this is now the
publishing standard used
by most Commercial publishing houses. So when you go to Safari.com
or O'Reilly, or Que those
documents are produced from a docbook. That said, you may pay $50.00
or more to buy it. But
if contact the publisher they'll let you have the docbook for free and
you can produce your own.
(I do that all the time).
Now, as for Confluence. I believe we should always be evaluating our
tools and migrating tools
when appropriate. We need to be testing the tools and using people to
test the tools to see how
people interface with it. Do they like it? Does it do what the
software engineers thing it should?
In other words, is the User's needs being fulfilled? Make no
assumption as if you are all-knowing.
That said, it is good that we are experimenting with Confluence. What
I notice now is that there
is a dialog of philosophies of how documentation should be created,
maintained and enhanced.
Points to consider for migrating documentation:
-- Is this a consistent pathway that the end user (Administrator,
Programmer, End User) will not
have to navigate to find an item in the new documentation compared
with the old? That could be
as simple as a title, index or page number. Or, is it so different
the user walks away frustrated
and says "forget it today, I don't have time for this"?
-- How is the documentation written in its context, language and
style. Mark Wood wrote a
few emails back about the bottleneck. This is subjective to a point,
but there is nothing worse
than reading documentation written by a bit-diddler and the end user
says "what did
this mean "use Ant to compile in the usual way" or "Pack your zoned
decimals". When the
real instructions should have been kindly written "Use the Ant Update
command to compile
your software in the usual way. Refer to ____ for further
instructions". The bottleneck can
come from variety of sources. In the current DSpace 1.6 manual, most
all committers have
been gracious in sending plain text in the jira ticket for me or
someone else to insert into the
docbook.xml. Larry Stone and Stuart Lewis have just gone in and made
the edits for sections and just
alerted me in the event I was editing the same chapter. Thank you for
that. They did a fine
job.
-- Documentation IMHO should never be independent of a release,
except for glaring errors,
and patches. (Okay, this is my philosophical rant and rave).
-- Programmers and users need to work together on this and make
strides in getting it done in
the first place.
-- Convention. I've created a document that contains information
about the editing I've done
with the current DSpace documentation. It has information about the
print.xsl (fo) and html.xsl
styles used, the dictionaries for spell check, the internal linking
and other pieces of information
used for publication. It is based on the Que and O'Reilly "house
rules" for publication. I haven't
included it in the manual, but perhaps another appendix is now
warranted.
So, where does leave us? Well, it really leaves us with things to
think about. Confluence
may eventually produce a product for us, but to throw the baby out
with the bath water doesn't
really help the situation.
I'd like us to think about using the Confluence project to "Shadow"
the current documentation
for the next release OR so.... and we can certainly "play" with it.
The larger community
could give us feed back on this and we can make wiser decisions and
have more in depth
discussions regarding individual philosophies.
Wiki's, IMHO are not academically rigorous for publication. (At
least for tenure at my institution
because Wiki's are not considered peer-reviewed).
A final note. Please look at the Apache.org site. The projects there
are managed documentation
via HTML. Postgresql is managing it's documentation via HTML and PDF.
Disruption Change is not something I enjoy these days. Maybe I'm
getting old.
But again, sometimes we need heresies to educate us. Without Martin
Luther, were would we
be today?
Jeffrey Trimble
System LIbrarian
William F. Maag Library
Youngstown State University
330.941.2483 (Office)
[email protected]
http://www.maag.ysu.edu
http://digital.maag.ysu.edu
"I must not fear. Fear is the mind-killer.
I will permit it to pass over me and through me..."
--Litany against fear....
------------------------------------------------------------------------------
This SF.Net email is sponsored by the Verizon Developer Community
Take advantage of Verizon's best-in-class app development support
A streamlined, 14 day to market process makes app distribution fast and easy
Join now and get one step closer to millions of Verizon customers
http://p.sf.net/sfu/verizon-dev2dev
_______________________________________________
Dspace-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/dspace-devel
