Split off from the topic Want to help contribute? Training provided.
Hi I'm Simon,
I'm an aircraft developer working on the old de Havilland Vampire model the StuartC and Boffo made.
Sorry to dig up an old thread but its the closest to what I wanted to say.
I have managed to extend the DH Vampire model to have some uv mapping and a full instrumentation panel in accordance with the RAF pilot notes for the Vampire F3.
My experience of the FlightGear project is one of mostly awe and fun tinged with a quite a bit of confusion.
I have been able to create a dream and fly it, fix the navigation so I can role play being a pilot in the 1950s cold war. Thank you FG developers and Stuarts team for making this relatively easy.
I wanted to reiterate the statements here about documentation. I hope to offer these comments with more detail about what a new user goes through and its not meant as a negative criticism (The achievement of one of the best Open Source games is evidence enough that FlightGear is powerful and impressive).
So the good stuff TLDR is
* Realtime fast game engine
* Amazing array of aircraft and instruments that can be used: Spaceshuttle, Jets, Prop planes just incredible.
* Geospatial base for creating scenery using PostGIS (nice!)
* Good rendering engines capable of atmospheric effects.
* Some nice rigorous standards- Use of XML, C++ code base, Nasal close to ECMAscript (code highlighting support)
After being involved with Blender for 6 years and seeing it grow from being very inaccessible to the best 3D tool today. I feel sure FlightGear could do the same thing if it had good core documentation. (Mostly lacking is standard API docs).
It also seems that this is hindering standard development of navigation, pressurization, oxygen, electricals, fuel and other systems because new users can't understand them easily.
The TLDR of the below is this
* The core reference documentation is largely incomplete
* XML properties API not documented in one location
* Top down system description missing
* Full & complete properties description missing
* Nasal API docs missing
* Read the source: Doxygen missing for FlightGear part of the source (Working for SimGear), source code comments are not extensive.
* Wiki is a good idea but should be where all documentation can be reached from: README files are not included
* Unneeded phrases in the docs which don't add to understanding written in colloquial style. If documentation is hard to do, no need to write more words than you need to
The wiki attempt is a good idea but often has missing information in what seems like the most important places. In many cases the depth of the documentation is there from the Aircraft Portal Page but there is no head document which provides the top down structure describing it. There is a tutorial style howto. The difference is that one gets you to the information quickly while the other is for learning it for the first time. Colloquial friendly language is fine in a tutorial but unnecessary in reference documentation.
I can't find a top level breakdown of how the flightgear system is structured. Concepts like systems, fdm, instrumentation, models are breezed over in the set file page.
An API auto description should be provided for the nasal API. I use Blender a great deal and they have excellent python API documentation which makes all the difference to scripting developers. Perhaps the Sphinx documentation system could be used for this as I don't think the API has to be python based.
The README docs by the admission of quite a few posts are incomplete. The wiki was probably meant to replace them so I am not sure why these were at least not autoposted into the wiki.
For example the core properties description has TODOs on the top level headlines. Sadly the style of writing in the documents I find indirect and often full of statements that don't impart information.
Falling back to 'Read the source': there are these issues
I have seen Doxygen mentioned but I can only find this for simgear.
I would expect this to accompany doxygen as a commentary with a module diagram
I started C++ coding over 20 years ago. I still can't understand the codebase in a way thats useable. Flightgear is large, complex and multi dimensional. I don't think with the limited code comments and no system description its fair to ask users to do this. Its just another barrier to getting more people on board.
Thanks for listening.
Simon.