[OPEN-ILS-DOCUMENTATION] no training session this Thursday, however...

[Dan Scott]

2008/4/24 Karen Collier <kcollier at kent.lib.md.us>:
> Jason, Dan, etc.,
>
>  Here are some thoughts and questions for going forward.
>
>  Maybe in a future training session, as a group, we could look through the Wiki and the DocBook outline to see what's missing and focus discussion on those areas?

That sounds like a good idea, although there's no need (in my mind, at
least) to wait for a meeting to start fleshing things out. This list
would be a good asynchronous discussion place!

>  It seems that most of what we've covered so far would fit under the "Evergreen End-user Documentation" link on the Wiki and in Parts IV and V of VII in The Book of Evergreen.  I wonder if the intent is for us to focus primarily on those areas, perhaps making them more prominent in the documentation with the assumption that that's what most people will be interested in, or if there are other areas of documentation that need work, for which we could be trained?

The staff client, by its nature, certainly is oriented towards part V
of the book, and I think that's where the folks who have been
participating in the online staff client training might best focus
their efforts for the time being. I believe that would also satisfy
the most common need for Evergreen users today, as well as of
potential Evergreen users.

>  The other thing I'd be curious to see would be a tour through the source tree, not necessarily in any great detail, but for example, what kinds of things would be found in the Evergreen directory vs the Open-ILS directory, or what's the logic used to divide different parts of the code into different directories.  Or how do I know where to start looking for the code affecting a particular feature for purposes of documenting it?

Right, that's starting to get into the technical reference section of
the proposed book table of contents. It's going to be really important
for being able to bring new developers and contributors on board
faster, but would be a lower priority than getting a base level of
end-user application in place (imho). Of course, if people want to go
ahead and start writing, I'm not going to stop them!

>  I also have some questions specifically about The Book of Evergreen, and Dan's intentions for that.  Should we be refining the Wiki with the assumption that parts of it will be lifted, polished, and inserted into the DocBook document?  Or is this meant to be original documentation, perhaps organized differently than the Wiki is that we should be writing and either sending to Dan or to this list?

What I wrote back in September (immortalized here:
http://open-ils.org/dokuwiki/doku.php?id=documentation:history_of_the_technical_writing_project)
was:

"""... I don't think writing in DocBook should be required
for those who don't have the time to learn DocBook; we should be able
to accept good doc contributions in plain text or other formats, and
convert it to DocBook on the contributor's behalf."""

So, again in my opinion, writing up sections in the wiki as you have
done would be fine, and then I can convert it to DocBook format; as we
convert a section into the manual, we can mark the page in the wiki as
being "done" and link to the relevant section of the manual. At some
point we'll get a better integration of documentation, wiki, and
website but just pulling all of the content together in a cohesive
fashion would be a fabulous start. (And as I've said before, if you
prefer writing in Word or HTML or pencil crayon on tissue paper, I'll
take whatever I can get!)

I really want to thank you, Karen, for all the work that you've been
doing on the documentation in the wiki. Next week, if I find an hour
or two, I'll try to pull what you have done into the manual just to
see how it looks - and hopefully that will inspire more contributions.

-- 
Dan Scott
Laurentian University