FlightGear documentation, core and other

[Johan G]

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.

[Johan G]

tl;dr - FlightGear is amazing, but I feel your pain

The source code and its documentation
I do not know all to much about the core documentation aimed at developers, though when I have been looking for answers for example like what bindings[1]/fgcommands[2] are there, I am at complete and utter loss without having a local copy of the repository and a grep search.[3] Also looking around in the source code (mind you I am not a programmer) it is sometimes really hard to figure out where a certain feature would live due to how things are structured, even though I have looked around in the code now and then for half a decade by now. Think in terms of taking half an hour or more to find out where a feature lives.

The wiki
As for the wiki, I consider it a mess, but is trying the best I can to at least give it structure. I have also tried to make it easier to use by documenting for how a wiki works and how to use it.[4] The main issue with the wiki as I see it is that I would like it to function and to some degree be like Wikipedia (I have experience from both the English and the Swedish Wikipedia, a lot more from the latter). The problem is that while most people have come across Wikipedia, they do not necessarily understand for example namespaces, templates or categories.

There was not always a style guide and all articles look different. Most templates still are still undocumented. Also, there are entire article series which I have a hard time absorbing since the structure, overlap and dependencies between those articles make my head hurt. Additionally, many editors seem to write like as if there was no tomorrow and no more commits would me made to FlightGear, for example not specifying which version of FlightGear a certain feature was introduced or deprecated at.

When I was new at the wiki I wrote what on Wikipedia would be called a "user essay" detailing the issues I had at the time.[5] Though some of the issues are no longer there, like the lack of a style guide and a Village pump, there is still a lot, lot more to do.


Edit: I should also mention the pretty much all discussion about the development of of the code for the FlightGear binary is taking place on the FlightGear developer mailing list.[6] Few of the core developers are active on the forum.

____
[1] Bindings (permalink)
[2] Howto:Add new fgcommands to FlightGear (permalink)
[3] fgcommands can apparently be added any place in the code, but there is no central registry or documentation of all of them.
[4] My wiki contributions in the Help namespace.
[5] User:Johan G/Essays/Essay:The FlightGear Wiki — Its structure, content and ease of use (permalink)
[6] [flightgear-devel] mailing list

[Thorsten]

I feel sure FlightGear could do the same thing if it had good core documentation. (Mostly lacking is standard API docs).

Historically at least that statement has no evidence going for it.

During my involvement with the FG project, I initially made the argument myself and was confronted with it a couple of times, in response I wrote detailed documentation for many features to create a low entry barrier.

Without exception, the outcome of that has been close to zero. The documentation has in no instance generated the hoped-for influx of new contributers.

So - realistically seen - creating documentation is by and large not a good use of my time - in the rare case someone wish to understand something, it takes me less time to simply answer questions - which has the added benefit that I can target the level of the answer to the audience.

I suppose other developers have learned similar lessons. Anyone who is seriously interested in core work will take the time to look around and ask questions - anyone who is not will not contribute much even with documentation.

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.

That'd be because there are no standard aircraft systems - you need to understand how the aircraft works, and then you need to select the tool for the job, and then you need to apply the tool.

An electrical system for a low-fidelity YaSim aircraft written in Nasal is a completely different beast from a high-fidelity JSBSim system.

Generally you'd research what craft have something already implemented which you could adapt, study how it is done, ask the maintainer in case of questions and work from there.

[legoboyvdlp]

I think you are right about the core documentation - however, the code doesn't come under warranty; I don't think there is any obligation to document. Thorsten feels that its a waste of his time that is better served answering specific questions, others may feel the opposite. Generally, newer code is better documented.

Nasal API docs missing

What specifically are you referring to, I have various wiki pages here, for example:
http://wiki.flightgear.org/Vector
http://wiki.flightgear.org/Category:Nas ... umentation
Nasal is one of the better documented parts...

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.

I fully agree with this. However, it is what it is; moving forward we can document the systems and we would be glad of any help. Speaking from experience, I have been recently working on the ATC subsystem. At first I was completely out of my depth, but after spending several weeks on it I somewhat understand the code and am in the process of revising / documenting it. For instance, see:
https://sourceforge.net/u/legoboyvdlp/f ... ontrol.cxx
where I have documented the ActiveRunway class so far, revised the while loop logic, and generally tried to make the code more readable.

If you would like to help, please do ask for assistance (and I would be glad of any assistance in return with C++ code in which I am still getting my feet wet )