Re: [Paparazzi-devel] Making it easy for new users

[Stephen Dwyer]

Hey Gerard,

Looks great!

Was your plan to kind of put most of this info in a single page? Or
break it up and have a getting started page that is like a heavily
annotated TOC with lots of links to other wiki pages? Just wondering
because most of the content is written (though perhaps not as
clear/concise and up to date as it could be). Definitely a few things
on the list that are in need of work, or missing altogether though!
Very comprehensive list you have developed though, nice job.

Also, when I do some wiki changes, I find it helps to use by User page
(http://paparazzi.enac.fr/wiki/User:Gtoonstra)  as a scratch page to
work on, make lots of little changes to, test out how things look etc,
then copy the content over to the original page. Sometimes I start
with what was on the original page, copy the source to my page, then
copy it back. You can also get others to review your work on your user
page too. Just an idea.

Would be fantastic if you were willing to put this work into documentation!

Thanks,
-Stephen Dwyer

On Wed, Oct 3, 2012 at 9:04 AM, Felix Ruess <address@hidden> wrote:
> Hi Gerard,
>
> nice!
> I don't really have time to look at this right now in detail...
> But you can put it on this wiki page:
> http://paparazzi.enac.fr/wiki/Documentation_Needed
> (And simply remove what is outdated or not needed anymore there...)
>
> Thx, Felix
>
>
> On Wed, Oct 3, 2012 at 4:44 PM, Gerard Toonstra <address@hidden> wrote:
>>
>> Hi Felix,
>>
>> As discussed, here's my draft proposal. It's a bit like a table of
>> contents that shows the
>> topics and order in which things are discussed.
>>
>> The objective now is to discuss this TOC on the mailing list and comment
>> where necessary,
>> or set up a new hidden page on the wiki with this TOC, modified to insight
>> and once considered
>> ready, populated with the actual content under each header.
>>
>> Rgds,
>>
>> Gerard
>>
>>
>> ========================
>>
>> Overview:
>> - Paparazzi is a complete system for control / monitoring of UAS. It is
>> composed
>>   of an airframe and a GCS.
>>    * What is the target group?  Is it COTS?  Who'll probably be able to
>> use it and who should
>>      look for other solutions?  What are comparable/competing projects?
>>    * What is an autopilot and what are its features?  How different from
>> manual control?
>>       How can paparazzi be used in incremental complexity (stabilized
>> mode, with GCS, autonomous mode, etc.)
>>    * What is a ground station and what are its features?
>>      = refer to 3-5 configuration examples of the use of paparazzi
>> autopilots.
>>      = refer to some prizes that were won with paparazzi.
>> - Ground Control Station in more detail
>>    * Computer choice and OS.
>>    * GCS software and where it's located. Different branches?
>>    * GCS part of the telemetry link
>>    * Explain basic GCS concept. What is an A/C. What is a "session"?
>>    * Explanation the function of most common PC processes.
>> - Playing around with the GCS
>>    * Explain that the GCS can run simulations without hardware. Invite
>> users to play around with it now.
>>    * Explain the simplest method of getting a simulated aircraft in the
>> air with some screenshots.
>>    * Provide an example how different configurations of airframes affect
>> the monitoring/control
>> - Aircraft explanation
>>    * Airframe choice.
>>    * The autopilot with attached sensors.
>>    * Explain how software will be configured for the airframe through XML.
>> - Electronics in more detail
>>    * Soldering equipment requirements
>>    * Choice of acquiring ready-made boards or create your own. Branch off
>> there.
>>      = Include warning about mix of 3.3v/5v levels on board and options to
>> deal with those.
>>    * Explain how sensors affect the capabilities of the autopilot.
>>      = List most common extra sensors, depending on application (matrix?)
>>      = Specify where to go for custom sensor integrations
>>    * List some distributors+types for the relatively specific Picoblade
>> housings+wires in
>>      different continents and how it's probably good to get a good couple
>> of those?
>>      (at least on lisa/m2).
>>    * Debugging hardware options
>>    * Bus pirate / oscilloscope / other tools are very handy to mention
>> here too.
>>    * Communications (as is)
>>
>>
>> Getting started for real....
>> - http://paparazzi.enac.fr/wiki/GettingStarted   is a walkthrough with
>> steps, but doesn't
>>   explain *why* things are done.
>> - http://paparazzi.enac.fr/wiki/Getting_Started is a nice base to start
>> from, but is outdated
>>    in parts.
>>
>> The two can be merged into one with more things added as to why things are
>> done prior to
>> getting the user to do it.
>>
>>   * Explain the directory tree of paparazzi (in a table).
>>   * Specify what's going to be done next and what the expected end result
>> will be.
>>   * Explain how the airframe XML impacts the
>> inclusion/exclusion/configuration of code
>>     and provide a template to work from.
>>     = defines
>>     = module loading (inclusion of optional parts)
>>     = firmware/targets
>>   * Explain the impact of the flightplan xml for the AP.
>>   * Explain what "settings" XML files are and how these impact the AP.
>>   * Explain the radio file and subsequent code generation. Include how the
>> radio should be set up
>>     (neutrals? pre-trimmed?) prior to configuration the endpoints.
>>   * Explain compile code and load cycle...
>>   * Identifying a successful firmware upload, execution of code onboard.
>>   * Troubleshooting compilation failures. Link to JTAG debugging.
>>   * What to do if all else fails?
>>     = How to use google to search mailing list and wiki.
>>     = Explain wiki layout.
>>     = Other resources that may be helpful.
>>   * Refer to HITL setup and debugging  ( requires working data modem ).
>>
>> Once it is all working on the bench....
>>   * next steps: crash prevention and double checking.
>>   * Choosing a suitable testing site.
>>   * Refer to tuning guide: ( tuning requires some updates, still mentions
>> IR sensors for example).
>>   * Checklist for use in the field, verifying proper function prior to
>> launch.
>>   * What to do in case of malfunction / how to panic.
>>
>> Advanced
>>   * Using buspirate/oscilloscope with paparazzi to analyze i2c/spi.
>>   * How to integrate a new module into a build.
>>     = What are modules (optional stuff, mostly sensors, actuators, etc..)
>>     = Choose existing one or develop your own+XML
>>     = How to find/verify options for modules in source code or XML.
>>   * How to make your own "targets" (use existing hardware to configure
>> GPS, etc.)
>>   * How to develop tests.
>>   * How to add new navigation routines.
>>   * How to modify the UI of the GCS.
>>   * How to add a new GCS process to the framework.
>>   * Starting points for integrating other systems on the communication
>> bus.
>>   * ... what else do new users eventually do with paparazzi? ... (think of
>> questions on mailing list).
>>
>>
>> Other doc work
>>   * Update existing documentation of hardware/software.
>>   * The values that can be set in certain modules or configurations (AHRS)
>> etc. need to
>>     explain a bit more the impact of that choice, instead of simply
>> stating the name
>>     of the algorithm implemented. In case readers are not familiar with
>> the theory,
>>     recommend a general setting that should service them ok. (disclaimer?)
>>
>>
>>
>> On Oct 3, 2012, at 7:26 AM, Felix Ruess <address@hidden> wrote:
>>
>> Hi Gerard,
>>
>> that would be great!
>>
>> Cheers, Felix
>>
>> On Sun, Sep 30, 2012 at 1:55 AM, Gerard Toonstra <address@hidden>
>> wrote:
>>>
>>>
>>> I wouldn't mind lending a hand there, I've got some time on my hands at
>>> the moment.
>>> As a newbie into Paparazzi, I'm probably in a good position to provide my
>>> personal feedback about the documentation.
>>>
>>> Most documents dive straight into the technical details without
>>> explaining what the goals are of the document or thinking
>>> about the context in which it should be read. Readers will only find out
>>> at the end if the information was relevant for them.
>>> For example, a great way to reformat the documentation is to focus on the
>>> application needs, why people choose for some AP
>>> and try to guide them to the relevant bits to find their information very
>>> quickly. This list doesn't have to complete and future-proof,
>>> a couple of most general examples is already a great way to let people
>>> know what's involved.
>>>
>>> The simulation of the GCS is a great way to lure people into how
>>> paparazzi works without having access to hardware. Should that
>>> not be on the frontpage like: "interested in learning more?  Download the
>>> GCS and play around with it".
>>>
>>> The Overview page also needs some work. It dives straight into how the
>>> separate components are constructed, which requires the
>>> reader to integrate these together to get a picture of how it works
>>> together and which pieces may be optional.
>>>
>>>
>>> Anyway... as I said, I have some time and ideas on my hand over the
>>> coming weeks to assist, if there's agreement on the
>>> format (a table of contents?) of a step-by-step guide for newcomers.  If
>>> you want me to, I could supply an initial proposal and
>>> then we discuss that on the list?
>>>
>>> Gerard
>>>
>>>
>>>
>>>
>>> On Sat, Sep 29, 2012 at 7:31 AM, Felix Ruess <address@hidden>
>>> wrote:
>>>>
>>>> Hi all,
>>>>
>>>> the wish for a step-by-step guide is coming up repeatedly and is
>>>> definitely what is missing for new users.
>>>>
>>>> It would be really great if someone in the community would take it into
>>>> his/her hand.
>>>> That doesn't mean that it needs to be written solely by that person, we
>>>> just need someone who will coordinate this a bit
>>>> (with hopefully other people helping out) to make sure it's consistent
>>>> and be persistent enough to see to it that we actually have a finished 
>>>> guide
>>>> at the end.
>>>>
>>>> Basically don't by shy about editing wiki pages, be concise (also have
>>>> the courage to actually delete some outdated info or move it to more
>>>> appropriate pages), be persistent...
>>>> If there is something unclear, make a note in the wiki and ask on the
>>>> list.
>>>>
>>>> Maybe you? Yes, you in front of the screen there ;-)
>>>>
>>>>
>>>> Different pages were started with intents similar to this, but never
>>>> finished:
>>>>
>>>> GettingStarted pages, which should be merged into one.
>>>> A lot of the information there is also redundant and can be probably
>>>> removed.
>>>> E.g. there is probably no point in duplicating installation
>>>> instructions, unless you think it really helps.
>>>> http://paparazzi.enac.fr/wiki/GettingStarted
>>>> http://paparazzi.enac.fr/wiki/Getting_Started
>>>>
>>>> http://paparazzi.enac.fr/wiki/Lisa/M/Tutorial/FixedWing
>>>>
>>>> I just quickly added some pages to the old
>>>> http://paparazzi.enac.fr/wiki/Documentation_Needed page.
>>>>
>>>> Cheers, Felix
>>>>
>>>
>>>
>>> _______________________________________________
>>> Paparazzi-devel mailing list
>>> address@hidden
>>> https://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>>>
>>
>> _______________________________________________
>> Paparazzi-devel mailing list
>> address@hidden
>> https://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>>
>>
>>
>> _______________________________________________
>> Paparazzi-devel mailing list
>> address@hidden
>> https://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>>
>
>
> _______________________________________________
> Paparazzi-devel mailing list
> address@hidden
> https://lists.nongnu.org/mailman/listinfo/paparazzi-devel
>