paparazzi-devel
[Top][All Lists]

Re: [Paparazzi-devel] Improving documentation

 From: Chris Gough Subject: Re: [Paparazzi-devel] Improving documentation Date: Tue, 20 Jul 2010 15:38:17 +1000

```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

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,
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,
>
>
> 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
>> http://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>
>
> _______________________________________________
> Paparazzi-devel mailing list
> http://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>
>

--
.

```