On Mon, Sep 5, 2011 at 2:45 PM, I wrote: > More comments when I get the time once I'm back.
Hi Jomo, I finally got the time to look at your work in detail. I think there's a lot of really good work here, and it obviously represents a lot of time and effort. Thanks again. I _really_ like a number of things you've done with the structure. The following comments look at what you've done as a contrast to the existing Manual, and with a view to changing The Manual: 1) The Briefing section (which covers some of the Take-off and In-Flight sections of the existing manual) looks like it is designed to get the first time FGer up and running quickly. I really like it as a concept, and it's something that the existing Manual doesn't provide. I think it goes into a bit too much detail (e.g. covering the keyboard XML format), and could be cut down still further to provide a simple introduction to choosing and aircraft, airport and setting the time/weather for a flight, along with an introduction to the controls. 2) The First Solo complements the existing tutorials well. Nice work! 3) Moving some of the detailed reference material (e.g. command-line options) to an appendix makes a lot of sense. 4) Your work highlights the importance of providing better navigation between sections. We should certainly be looking at how we can improve navigation within the HTML version of The Manual. It would be great if we could have each chapter in the bar on the top, along with a section drop-down to provide straightforward navigation. Taking a step back, IMO there should be three separate sections to The Manual: a) A Getting Started Guide b) A Reference Guide c) Tutorials In fact I think that was the plan ages ago, but initially only the first was created (hence the filename - getstart.pdf), and over time its scope expanded to cover all three. At present the first two are combined, but your work shows that we really should be separating them more, so that the first Getting Started section covers the basics, and provides references to the detailed documentation in the Reference Guide. Martin has always been (rightly) keen to limit the PDF size of The Manual to ~ 5MB, on the basis that if it is any larger it becomes difficult to download and browse. It may be the case that we should look at splitting the tutorials off from the main manual, either as a single PDF containing all the tutorials, or as individual PDFs. This would have the advantage of allowing additional graphics withought impacting the main manual filesize. Food for thought! In terms of contents, I spotted the following issues on a quick skim through: - "The FlightGear-Manual" should be "The FlightGear Manual" - In English we don't use the subscript quotation mark „. - The default Windows directory on an Engish system will be under "Program Files", rather than "Programm Files" - Installation needs to cover the (newish) FG_AIRCRAFT environmental variable. (Yes - The Manual doesn't cover that either at present ;) ) - VFR X-Country refers to KRHV as the destination airport in "Merge into the pattern" - In general there's an assumption that the user is going to use the command-line interface. I'm not sure that is valid - we should be trying to describe how to perform an action using either the command-line or GUI if possible. I also spotted a bunch of minor typos and places where the the English phraseology would be slightly different from the translation from German. To be honest, it's more hassle than it is worth typing them out here for you to transcribe them again into your HTML - they aren't major issues but small readability improvements. With access to the source code I could spend a good couple of hours going through and making minor corrections. I hope this helps. Finally, I think there are two related issues we need to address before we go any further: 1) You have a concern about copyright and presumably licensing, and from your previous email don't seem very keen to have your work released under the GPL. Can you explain in a bit more detail what your concerns are please? The Manual, like the rest of the FG base package, is released under the GPL, so this may stop any integration work in its tracks. 2) You've obviously put a lot of work into this. Martin and I have presented our view of why integrating this into the latex source of The Manual is the best way forward, but that is going to involve further work and will inevitably mean re-doing some of the work you've already done. What is your view - do you have any appetite for integrating this, or do you think there is a better way forward? Best regards, -Stuart ------------------------------------------------------------------------------ Why Cloud-Based Security and Archiving Make Sense Osterman Research conducted this study that outlines how and why cloud computing security and archiving is rapidly being adopted across the IT space for its ease of implementation, lower cost, and increased reliability. Learn more. http://www.accelacomm.com/jaw/sfnl/114/51425301/ _______________________________________________ Flightgear-devel mailing list Flightgear-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/flightgear-devel
