Forum .LRN Q&A: Help With .LRN User Documentation

Posted by Bruce Spear on 10/29/03 05:18 PM

I've prepared a tutorial for users new to .LRN, available at:

http://home.arcor.de/civici01a/programming/docs_1user.htm

And I'm looking for others who might have done somethink like it themselves, who might want to help me make this document better, who might include me in an existing documentation group or help form a new working group.

Anyone interested out there?

All the best,

Bruce

2: Re: Help With .LRN User Documentation (response to 1)

Posted by Deirdre Kane on 10/29/03 07:44 PM

Bruce,

I thought i replied to you already, but i came back in and my post was gone.

If it will help you and you don't already know about it, there is documentation for dotLRN at http://dotlrn.mit.edu/documentation.

DeeDee

3: Re: Help With .LRN User Documentation (response to 1)

Posted by Bruce Spear on 10/30/03 01:22 AM

Thanks DeeDee! Right, I've started with the Sloan docs, am cutting them down in size, and developing a different emphasis. I am finding that our people ask a variety of questions which do not appear in those documents, that they will not read more than a couple of pages at a time, and that they demand different kinds of explanation. So, for the first few weeks, I'm basically editing and tailoring to local needs. I am hoping to gain some experience on these introductions to the technology so I can move on to advice on integrating the technology into the classroom and workflow or curriculum, beginning with such basic exercises as the minute paper. I am after a more qualitative understanding of the uses people my put this technology to, and by editing and rewriting the most basic instructions, trying to get closer to the user experience.
All the best,

Bruce

4: Re: Help With .LRN User Documentation (response to 3)

Posted by Matthias Melcher on 10/31/03 11:00 PM

I would like to help (more with feedback than with actual wording since I am no American).

Can the document be separated into
- a local/diff part containing site-specific data and recommendations, and
- a central/head part that can be copied, and ideally could be a basis for versioning and translation?

One recommendation that not everybody will like to copy, for instance, is to accept "all cookies" rather than "session cookies". Also, in Deidre's text, the humourous introduction is great for some audiences but not for all that we would like to target.

If the local end version could be derived by applying diffs to the newest respective head version, this would save much rewriting and adopting efforts.

Matthias

5: Re: Help With .LRN User Documentation (response to 1)

Posted by Malte Sussdorff on 11/01/03 11:12 AM

While we are at it, as more universities in Germany start to pick it up, maybe some people could help by translating the User Documentation into German (and use the Germans translation messages done by Anja et.al.) Hello fellow German speakers out there ?!? ;).

6: Re: Help With .LRN User Documentation (response to 5)

Posted by Matthias Melcher on 11/03/03 11:11 AM

Quality translation required for decent usability cannot be done just along the way (while we are at it). Even with the short messages, it was (and still is) almost impossible to do deliver quality as long as the English orginals are poor and unstable. For more text, as end user documentation, it is even more important that it is
- usability tested
- sufficiently stable
- or/and controllable by reasonable versioning.
Therefore I was raising the question in my posting above if /how we can do the versioning. (I could be mean and suggest using dotLRN filestore versions but every text worker will get angry with this and will require a proper revision function of a word processor).

7: Re: Help With .LRN User Documentation (response to 6)

Posted by Bruce Spear on 11/03/03 03:23 PM

Interesting questions, all. I'm tempted to ask how the writing of documentation can be compared to the writing of software, in which case, versioning models make a lot of sense. My immediate interest is much closer to the learners. First, how can I write tutorials that my new users can use in 30 minutes or less. Second, how can we build feedback and assessment into the documentation to the end of helping instructors and users see how well they are doing and what advantages teaching/learning using .LRN might offer. That is, I am trying to imagine how we might prepare documentation that would lead users to embrace the technology because the benefits would be immediate and obvious; thus, instead of writing "an introduction to the functions," I would write/design "productive learning activities you might try using .LRN". How about that?

8: Re: Help With .LRN User Documentation (response to 1)

Posted by Jens Hill on 11/03/03 07:16 PM

Hello User,

we began for our participants a small documentation write. In regular distances we will post the document. Who wants can get the PDF File under mailto:brand@academy24.com. Alternatively it goes also about the entrance ecampus.academy24.com and the port 8000.

Thomas Brand
academy24

9: Re: Help With .LRN User Documentation (response to 7)

Posted by Matthias Melcher on 11/06/03 10:22 AM

<bruce>how the writing of documentation can be compared to the writing of software, in which case, versioning models make a lot of sense</bruce>

Once we start COLLABORATING on documentation, we need some way to ensure that contributed efforts can be reasonably re-used in forthcoming updates, otherwise most people will prefer to stick with their own monographs.

Of course, revision control with text is not as simple as line-wise cvs diffs in software versioning. But who should try and learn how to collaborate on shared documents if not the promoters of a collaborative system?