[Using Sakai] End-User Documentation

[Marshall Feldman]

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 <mailto:sean.keesler at threecanoes.com>
>
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-user/attachments/20101003/b341bfac/attachment.html