Re: [Paparazzi-devel] Re: Improving documentation

[Chris Gough]

I get it, my perspective is weired. Your not the first person to point
that out to me, I don't object (it's not like I have any choice).

I'm trying to look at the whole picture, slightly bigger than just
documentation; What do people need when they learn to use paparazzi?
"Surfing the web" is how a prospective/novice users end up embarking
on a paparazzi project.  "Learning the code" is how a paparazzi user
with basic skills moves to a more intermediate level. Intermediate
students need complete and accurate references (+1 from me on doxygen,
is OCamldoc any good too?). Novice/Basic students (e.g. "purchase till
AUTO2 flights") have different needs.

In general terms, I was suggesting we analyse "who needs what" before
launching into a project to create more documentation. Poine asked for
discussion on "what topics to pick". I proposed a formal method for
making a well reasoned choice. Whatever, an informal version could
work too. How about a "getting started" wiki menu item, containing
information about "what skills do you need to achieve your first Auto2
flight". I.e. just describe the skills, don't try and teach them.
Maybe link to other "resources and activities", but perhaps later
these could be elaborated and refactored into "topic guides" or some
such.

Chris Gough



On Tue, Jul 20, 2010 at 11:35 PM, Todd Sandercock
<address@hidden> wrote:
> doxygen is a fantastic idea!!! would make learning the code much easier
> ________________________________
> From: Christophe De Wagter <address@hidden>
> To: paparazzi-devel <address@hidden>
> Sent: Tue, 20 July, 2010 9:35:40 PM
> Subject: Re: [Paparazzi-devel] Re: Improving documentation
>
> Just another (maybe weird) perspective:
> The documentation that is most useful to me is "doxygen" and when even this
> fails it's down to the "grep" command. It is quite hard to choose which
> folders to include in doxygen (tiny/booz/lisa/common code/autogenerated
> code: var) and most of the lost time is due to searching where the code for
> a certain routine is located or generated from. I think anyone willing to do
> autonomous flight should be encouraged to read at least the main routine and
> the control code?!
> "In a project where fast evolution in code exists, the safest way to get
> code and documentation in sync is when they are written next to each other
> in the same file."
> Could we link a doxygen manual to the wiki? (with color coded pages for
> tiny/booz/lisa/common/gcs/etc...). Making this will (likely) raise questions
> as how to best organize code (tiny/lisa/booz) and how to know for instance
> which module can run on which platform....
>
> airborne
> airborne\architectures
> airborne\architectures\arm7
> airborne\architectures\arm7\60Hzloop
> airborne\architectures\arm7\500Hzloop
> airborne\architectures\stm32
> airborne\flightcode
> airborne\flightcode\fixedwing
> airborne\flightcode\fixedwing\modules
> airborne\flightcode\quadrotor
> airborne\flightcode\quadrotor\modules
> airborne\flightcode\common
> airborne\flightcode\common\modules
>
>
> _______________________________________________
> Paparazzi-devel mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>
>



-- 
.