[OPEN-ILS-DOCUMENTATION] Where to put reviewers notes .. Re: Evergreen DIG Test Server Available

[Karen Schneider]

> Question 1:  How do we determine what to document?  Do I document a
> separate page for if you are upgrading OpenSRF?  Or do I amend the current
> documentation so that it is clear that some steps only relate to a new
> install?
>

Dan Scott, with his professional background in documentation, may have more
insights here, but I'd see the chapter being about upgrading, and then the
chapter would "fork" (to use a word that has been popular in open source
circles lately ;-) ) to instructions with/without upgrading opensrf.

Note that through the Miracle of the Web, online DocBook-generated manuals
can cross-reference sections, chapters, and books quite easily--well,
perhaps not "quite" easily, but once you get the hang of it, these
references work well. So what you might do before anything is sit down with
a legal pad and a pen and sketch the outline of the chapter you're drafting.


Repke, it's better to have any notes documented on the wiki than stuck in
folks' heads. So if you get it on the wiki, kudos to you!

Question 2:  I am using Ubuntu 8.10, so my commands were (very) slightly
> different.  Do I just state that these instructions are for Ubuntu operating
> system and hope that if someone is using Debian they know the difference?
>  Or do I add the different commands in the same step indicating which
> operation system they are for?  I guess, the underlying question here is
> should we only be documenting in the preferred/most widely used os or should
> we try to accommodate both?
>

Well, that is a very good question. Take a look at how PostgreSQL handles
that:

http://www.postgresql.org/docs/8.3/interactive/install-requirements.html

What do you think?

(I checked out the MySQL upgrading instructions, and felt they did not do a
great job on the "different OS" instructions.)


>
> While the current documentation is good, I do think it requires that the
> user has a solid foundation in Linux commands.  I might be over thinking
> this, but I would like to create documentation that is easy enough for a
> person with average technical skills to follow.  I have the feeling that
> this is important for the growth of the Evergreen community.  So, if anyone
> has any thoughts on this, please share!
>


Definitely, the more people who can get Evergreen up and running without
tears, the better it is for the community!

-- 
-- 
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| kgs at esilibrary.com
| Web: http://www.esilibrary.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20090924/f97b3c4f/attachment.htm