Re: [Paparazzi-devel] Improving documentation

[Chris Gough]

This is something I have also been thinking about recently. Sorry for
the long story; seriously, it starts with "Once upon a time..."

...I used to be a teacher at a polytechnic institute (TAFE). I did
"courseware" development as part of that job. We used a formal method
called "Learning Needs Analysis" before working up a new course. In a
nutshell, it's a "copetency-based training paradigm" where each
training package addresses the gap between a students current
competency and some target competency level. I think it would be
helpfull/relevent here.

Imagine there was a model of all the competencies (in the paparazzi
domain) that you might need. Simply a two dimensional matrix, with the
competency-name on one axis and level of competency on the other. For
example, these competency names:

 * airframe aquisition
 * manually controled flight
 * workstation aquisition
 * autopilot hardware aquisition
 * and all the rest...

Might have these coresponding "level of ability" scales:

 * buy an RTF kit, ..., engineer a purpose-specific airframe from the ground up
 * crash trainers infrequently when doing circuits, ...,  competition
RC pilot with success in multiple classes of event
 * install a virtualbox appliance on your windows laptop, ...,
linux/ocaml virtuoso
 * buy an "all you need kit", ..., hack on the next generation of hardware
 * etc...

The competency model is essentially a list of the dimensions in the
learning problem-space. A pupil's existing situation is an address in
that problem space, and so is their goal. The vector from a pupil's
current situation to their learning goal passes through the necessary
intermediate stages. Describing that vector is "doing a learning needs
analysis" for that pupil.

I'm not suggesting we need to do a learning need analysis of anybody,
just that a competency model would be a useful ontology, it could be
used to align various activities:

 * articulate the minimum competency required to achieve a certain
objective (like first AUTO2 flight)
 * help new users set appropriate goals (self-assess their competency
vs. the goal), naturally afford their project development roadmap
 * create a conceptual framework to catalogue documentation on the
wiki, link to other documentation etc
 * identify gaps or thin patches in existing the documentation
 * guide development by putting "usability barriers" into context

I agree writing a new tutorial is always worthwhile. I also agree that
there is a lot of good stuff out there already, so much in fact that
it's a challenge for new users to access (especially if they are
impatient or otherwise undisciplined students). Last time I looked,
one RC groups paparazzi thread had over 170 pages; quite comprehensive
but for people who don't know what they don't know, more cohesive
documentation would make it easier for them to learn.

What if the next step was to make a new mailing list
("paparazzi-users" ?) and a new wiki page, then encourage a lively
debate (on that list) from the Paparazzi User Training Special
Interest Group about what competency levels are needed to reach what
milestones/objectives, and try to capture the results (on the wiki
page). After that discussion dies down, the mailing list could live-on
as a support forum and place for newby questions, where it could
continue to inform the evolution of the wiki (and system usability).

I'm only a beginner myself, but I'd be very happy to listen in on
discussions between more knowledgeable people and make like a wiki
gnome. I'm also happy to host a mailing list server and whatever else
for the purpose, but think it's probably better to extend what already
exists.

Would anyone else like to take a User-Training SIG type discussion offline?

Chris Gough

On Tue, Jul 20, 2010 at 3:41 AM, Adam Spence <address@hidden> wrote:
> Hey Poine,
>
> It's just my 2 cents worth but I think the documentation is perfectly
> adequate. I think what people struggle most with is reading all of it to get
> an understanding of everything. I think we live in a world where people
> don't expect to have to read the user manual anymore and can use software as
> it is but expecting it to be intuitive.
>
> I think the XML configuration files are excellent but I wonder if it would
> be better to put together a flexible interface for the XML config files. I
> appreciate the challenges there are but this could make Paparazzi more
> accessible to many people.
>
> I also think the other biggest issue is with Linux. The pre-installed ubuntu
> images are excellent but it still requires the user to be able to format or
> re-partition a computer. They also have to go through a number of what may
> appear obstacles before it works.
>
> I love linux and am a great fan but I think for average joe who is used to
> Windows it's a big step. I've recently moved across to using Virtual Box as
> my work laptop is up to the task and have to say that everything is working
> out well. I wonder if it would be appropriate to maintain a virtual hard
> drive for virtual box.
>
> With regards to that I wonder if another improvement would be convenience
> icons which perform things like SVN updates etc. I know all of the hard core
> linux gurus out there will be disgusted by the thought (just be happy I
> didn't say port to Windows!) but we have to be practical if we want to make
> the system more accessible.
>
> Like I say, just my 2 cents worth!
>
> Cheers,
>
> Adam
>
> On 19 July 2010 10:39, antoine drouin <address@hidden> wrote:
>>
>> Hello Wolrd
>>
>> Eric and I had a long discussion about the Ultimate Question of Life,
>> The Universe, and Everything, and also about what would be needed to
>> improve Paparazzi.
>> Of course we quite quickly stumbled on usability issues and from that
>> to documentation issues.
>> Eric is willing to experiment with different ideas for the
>> documentation and for that he figured that writing a pilot on a
>> particular topic would be a good starting point to gather unstilted
>> criticisms.
>> Now the question arises of what particular topic should he pick ?
>> We're eager for your suggestions.
>>
>> Regards
>>
>> Poine
>>
>> _______________________________________________
>> Paparazzi-devel mailing list
>> address@hidden
>> http://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>
>
> _______________________________________________
> Paparazzi-devel mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>
>



-- 
.