Hi Jorg, Firstly, apologies for being so late to comment. Too many other things going on, and not enough time to think about and comment properly.
The main thrust of your proposal is to change the current process, which can broadly be described as: Latex -> PDF/HTML to one where you have Wiki -> HTML AFAICT , we gain: - easier editing for those not familiar with Latex - probably more contribution as it's easier to edit - cross-referencing between completely separate documents But we lose - the ability to produce a nice hardcopy manual, - real control over the content - anyone can edit the source. - proper version control (how do you differentiate between what is relevant to 2.6.0 and 2.4.0?) I'm afraid I don't see this as a step forward. Further comments below. On Fri, Feb 24, 2012 at 10:28 AM, Jörg Emmerich wrote: > I admit: Also I still read my Newspaper in hardcopy during breakfast - > but for more details I follow the advise (or QR-code) inside the daily > Newspapers or TV-news to look up details on their homepage. And surely a > professional designer must study lots of hardcopy books (and pay lots of > money for those!) - but I do not believe that nowadays any PC-USER of a > "hobby-product" (may he be high or low skilled) will go to a Public- or > University-Library for details! (Remember: We talk about a "getstart for > a hobby" - not a "Masters-Degree in..."). The name getstart.pdf is historical. The Manual is intended to be an definitive guide to the entire simulator. IMO there is certainly space for a "new" Getting Started guide, probably as a new chapter in the existing Manual, though it could be elsewhere. > And I am pretty sure that not many users of FlightGear print the > "getstart.pdf" - and they will do so even less in the future! And even > if it gets printed, it is printed on standard PC-Printers! Or can I buy > that book anywhere with a superior Print-Quality? And do I get a printed > update for new versions? (Now every 6 month?) It would be pretty straightforward to use cafepress or one of the many print-on-demand websites to provide a proper printed manual. I looked into this a couple of years ago, but never actually got as far as printing a copy. Might be worth looking into again. > Did you notice that most products you buy today, do not have a real > "User-Manual" any more - but tell you an Internet-Address to look it up? > (A modern way to avoid the law to provide those manuals in the national > language!) As pointed out by Martin, we shouldn't be aiming for the lowest common denominator. FlightGear is targetted as a professional product, even if it's created by volunteers and mainly used by hobbyists. Having good, definitive, documentation is part of that. > Anyhow: Did you ever try e.g. (with Firefox 10.0.2) > "http://wiki.flightgear.org/Howto:_Using_QGIS_and_satellite_pictures": > --> mouse-click "File" --> "Print" (or "Print Review") and compare that > to the "getstart.pdf"? Do you see a significant difference in > printing/reading quality? Yes. The pdf file has far better rendering of characters, sentences and paragraphs, and the general layout is far superior and easier to read. I certainly couldn't read tens of pages of printed HTML, but I could happily read the equivalent rendering from PDF. > I would support the need for an "authoritative raw source" - if there is > the manpower to maintain it! - over decades? It surely would be a good > reference for all upcoming versions. We already have an "authoritative raw source" (Latex), and there has been sufficient manpower to maintain it for many years. It keeps up with the major changes with each release. Contributions are always welcome, and it can certainly be improved. > I admit: Page-Referencing (and especially the old style Indexing) is a > problem for HTML -- if reading hardcopy! In the reverse it is impossible > to reference between multiple PDF-documents to unique text-positions! So > neither approach is the "Golden Egg" in a mixed environment. I tried to > compromise for that with: Smaller "books" (so headers are enough - no > real need for page-numbers). You are conflating multiple issues here. The Manual is already available in HTML format, and already easily references between unique text positions. The Manual is also currently provided in a single PDF, so there is no need to reference between different unique text positions in different PDF files. I understand that you'd like to split the Getting Started Guide away from The Manual, which is what drives the question of being able to cross-reference between different separate documents. Your solution appears to be to split it into different HTML files, linking between the two. Exactly the same result can be provided by creating the Getting Started Guide as a separate section of The Manual. The HTML version would be able to cross-reference between the two parts. The PDF file would contain both the Getting Started Guide and The Manual, however that's just a bonus, as a PDF isn't something that's provided at all with your solution. > The amount of cross-referencing may have some negative side effects, > when reading top to bottom and jumping to each and every reference - but > surely it is extremely positive having the possibility to jump to more > details (when wanted/needed) and directly return to the place you were > -- all of that with two mouse-clicks instead of wetting your fingers and > search through lots of paper-pages!). As mentioned, you can already do this by accessing the HTML or PDF version of The Manual on your computer. > In addition those smaller books with a lot of referencing ensure that > each subject needs to be described only in one chapter - thus changes > have to be "updated" only once - and not in several books and/or > chapters. Latex supports including the same information in multiple locations from a single source. It's trivial. > Especially the aspect of controlling changes promotes the use of WIKI, > because whoever is concerned can set a mark to be notified about any > changes made by anybody - and can delete or correct changes made -- see > the history options in the FGFS-wiki. So you may have lots of observers! Frankly, allowing anybody to edit The Manual is not going to result in better documentation. 1) What they write may not be accurate - typically it will reflect their own experience, and possible mis-understandings. I sometimes go and read the source-code to ensure that my understanding of a specific feature is correct before I document it. 2) They may write to a suitable standard. Writing technical documentation is a skill, and more difficult to acquire than many people realize. To address these issues, changes need to be review by someone with enough familiarity to spot errors, an a good enough grasp of English to check the quality of writing. At present this is handled by changes being emailed to Martin or myself who review them before committing them. Anyone is welcome to contribute, but we have checks to ensure that what they are contributing is good enough, and we have the option of asking the contributor to make changes and re-submit their changes for review. This ensure that while The Manual may become out of date due to changes in the program itself, any change made improves the accuracy. This is unashamedly elitist, and very similar to our approach to the source code. A wiki lacks these checks, and instead relies on other people to spot issues after-the-fact, and then correct them themselves. So, inaccurate information may remain in the wiki until it's corrected, which may be well after a release is distributed containing the new manual (you were intending to deliver the documentation with the release?). This would be the equivalent of allowing anyone to commit changes to the source code, and only looking for bugs afterwards. > To the end: I was surprised not seeing any comments to the problem of > "multi-lingual" support - which was the starting point for this > controversial work of mine. I am sure nobody explicitly wants to > restrict FlightGear just to people being able to read and write English. > But I guess this point is an unsolved question for todays > "getstart.pdf". So I guess there is no problem if I just input my German > version into the FGFS-WIKI - not as an "authoritative raw source" - but > hoping it may help some other "Tongues" for their translations. > joe Providing translations of The Manual should be straightforward. If someone was to produce a Latex translation, I'm sure I'd find a way to add it to our build system in such a way to keep it in sync. -Stuart ------------------------------------------------------------------------------ Keep Your Developer Skills Current with LearnDevNow! The most comprehensive online learning library for Microsoft developers is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3, Metro Style Apps, more. Free future releases when you subscribe now! http://p.sf.net/sfu/learndevnow-d2d _______________________________________________ Flightgear-devel mailing list Flightgear-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/flightgear-devel
