[Using Sakai] End-User Documentation

[Sean Keesler]

I didn't mean to derail...I get your point...yet, there IS a lot of
undocumented functionality and a lot of people that would like it
documented. If the institutions that built the tool don't have the
resources available to write it, I think that another institution could
partner up on the project to document it.

At one point there was a development process described that listed out some
"stages" that a project would go through....R&D, Incubation, Development and
Maintenence (
http://confluence.sakaiproject.org/display/MGT/How+Sakai+Development+Works).
Somewhere in that process documentation of the project was supposed to be a
criteria for deciding if it was ready to be part of the Sakai release.

I think we're at some interim stage where a lot of our legacy tools didn't
go through that process and we're yearning to backfill the documentation,
but recognizing that there are many barriers to getting that done.


Sean Keesler
130 Academy Street
Manlius, NY 13104
315-682-0830
sean.keesler at threecanoes.com



On Sun, Oct 3, 2010 at 11:38 PM, Marshall Feldman <marsh at uri.edu> wrote:

>  Sean, et al.,
>
> I think my post started this discussion, which I'm very glad to see.
>
> But the drift to discussing wikis, etc. misses one of my most important
> points. THERE IS NO SUBSTITUTE FOR DEVELOPER-PROVIDED DOCUMENTATION.
> Anything else is, by definition, guesswork. Documentation should not be
> optional. Instead, software without developer-provided documentation is not
> ready for prime time. Period!
>
> Maybe some of this drift is due to the fact that so much of Sakai is
> focused on novice users. Since there's an art to writing tutorials,
> tutorials may not be something to expect from developers. What I was asking
> about was technical documentation for end users. I just don't see how people
> who did not write the software can contribute to documenting how it's
> supposed to work. Even if someone were to read the code and could "prove"
> the software works a certain way, this would still not necessarily be the
> way the software is supposed to work.
>
>     Marsh Feldman
>
>
> On 10/1/10 [Oct 1, 10] 11:52 AM, Sean Keesler wrote:
>
> Slip of the fingers...I meant confluence, not Jira. :)
>
>  I hear that your requirement is that the "official" community
> documentation should be exportable in a format that can be imported into a
> free wiki engine. I know that confluence can export spaces into XML docs,
> which I imagine could be parsed and imported into other engines (such as
> MediaWiki).
>
>  Since the community docs are insufficient, the priority for a small
> support group is to create their own, rather than contribute to the
> community docs. I'm wondering what we could do to reverse the trend; to make
> the obvious choice to contribute to the community docs SO THAT they can use
> them locally.
>
>  To be blunt...would switching to a different wiki (mediawiki) tend to
> make the whole thing more appealing? or....is the issue simply that of
> resources...as it so often is?
>
>
> Sean Keesler
> 130 Academy Street
> Manlius, NY 13104
> 315-682-0830
> sean.keesler at threecanoes.com
>
>
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-user/attachments/20101004/d8ed67f6/attachment.html