Board index FlightGear Development Documentation

Setting up and coordinating Documentaton efforts?

Discussion of the FlightGear documentation, how it can be improved and coordination of people working on it.

Re: Setting up and coordinating Documentaton efforts?

Postby Hooray » Thu Nov 22, 2012 2:14 am

Yes, I really have to agree regarding the images used in the manual. Last I checked, the manual contained lots of outdated images/screen shots.

However, many of them were probably not updated because that does indeed mean lots of manual work currently.

And it would be pointless to update things now for different aircraft/GUI dialogs...

However, we should really be looking for an automated solution to specify screen shots procedurally and use fgfs to create them using meta information.
So that the images in the manual can be also updated by running fgfs and creating the latest screen shots with meta data in the form of "c172p-set.xml @ KSFO 28R".

Manually updating all images is LOTS of work. And just think about all the GUI dialogs that were changed recently ... and that WILL BE changed again once we have a fully canvas based GUI system.

Stuart's tutorial system demonstrates that we already have a scriptable simulator that can zoom in/out of the cockpit panel procedurally, and focus certain instruments - and we already do have bindings for creating screen shots. So in combination, these features could be used to create up to date screenshots of aircraft, dialogs etc.

Thus, it would seem absolutely possible to add a "scripted-screenshot-mode" to FG to create screen shots automatically for different aircraft/airport/situations/configurations and write them to a folder, where they can be picked up by the LaTex tool chain to be embedded into the final PDF file.

Now that would really be a time-saver that could actually improve the documentation significantly ... and it would be far superior to manual efforts, even wiki-based ones ;-)
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 12707
Joined: Tue Mar 25, 2008 9:40 am
Pronouns: THOU

Re: Setting up and coordinating Documentaton efforts?

Postby jharris1993 » Thu Nov 22, 2012 5:23 am

sa7k wrote in Thu Nov 22, 2012 1:13 am:Jim, about the manual, what do you think is in most need of correction or of updating?
I had the impression that the most needed was the images which confused me when reading because of the differences with the actual in-sim c172, but I think the manual is mostly correct.

sa7k,

Actually, at this time I don't really know.

I had "looked at the manual" and noticed some discrepancies and areas that I thought needed improvement, and then discovered that I was looking at a much older (2.6 vintage? 2.0 vintage?) manual. ( :oops: ) I've just downloaded the New and Improved 2.8.n manual and plan to read that just as soon as the Thanksgiving Holiday Madness is over.

Seriously, one of the ideas I had, and may still have after I read the new manual, is to fork the documentation into two major parts - a "Users Guide" and an "Installation and Setup Guide".

The User's Guide would consist of all the parts of the manual that are not implementation specific, especially with regard to setup and configuration.

The Installation and Setup Guide(s) would be split by O/S and (if necessary) architecture. This way the user can be given very specific, relevant and accurate installation instructions based on his system, without a lot of other unrelated installation stuff tossed in to muddy up the waters.

I thought of this, and still think it may well be valuable, because one of the most confusing parts of the manual is the fact that the 'nix, Mac, and Windows installation and configuration instructions are all blended together in a mish-mash of conflicting and confusing steps. (At least this is how it occurred to me when I read the 2.whatever version of the manual that I dredged up from who knows where.)

I would be willing to step up and take ownership of the Windows installation and configuration manual, as well as helping with the initial fork and separation of the various sections.

What say ye?

Jim (JR)
What say ye?

Jim (JR)

Some see things as they are, and ask "Why?"
I dream things that never were, and ask "Why Not".

Robert F. Kennedy

“Impossible” is only found in the dictionary of a fool.
Old Chinese Proverb
jharris1993
 
Posts: 154
Joined: Sun Nov 18, 2012 10:20 pm
Location: Worcester, MA. / Moscow, Russia
Callsign: $%^&ing Idiot!
Version: Whatever..
OS: Win-10/ Linux MInt

Re: Setting up and coordinating Documentaton efforts?

Postby Hooray » Thu Nov 22, 2012 6:26 pm

I agree with your proposal, I think that would be a good step to improve the documentation significantly. The idea itself has been discussed a couple of times on the devel list, however there was some inertia (read: resistance/objections), namely by the maintainers of the manual - so it would be up to you to discuss and coordinate this with Stuart.

Unfortunately, I need want to point out that a similar attempt at improving the FG documentation has been recently implemented/discussed and was basically rejected, I suggest to read the following threads for some additional background info:

http://www.mail-archive.com/flightgear- ... 28077.html
http://www.mail-archive.com/flightgear- ... 33665.html
http://www.mail-archive.com/flightgear- ... 36145.html

So there are clearly people interested in working on the docs, however, successful collaboration seems currently hard to achieve, so you should be aware of these challenges.

But you should be on the safe side by coordinating everything with Stuart, who is not only the maintainer of the manual, but who also has commit access so that he can apply changes meanwhile. In addition, he's a FG core developer, too.

PS: If you are serious about contributing, make sure to also read: viewtopic.php?f=42&t=15267
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 12707
Joined: Tue Mar 25, 2008 9:40 am
Pronouns: THOU

Re: Setting up and coordinating Documentaton efforts?

Postby jharris1993 » Thu Nov 22, 2012 8:09 pm

Hooray wrote in Thu Nov 22, 2012 6:26 pm:I agree with your proposal, I think that would be a good step to improve the documentation significantly. The idea itself has been discussed a couple of times on the devel list, however there was some inertia (read: resistance/objections), namely by the maintainers of the manual - so it would be up to you to discuss and coordinate this with Stuart.

Stuart doesn't seem to be that far away from this, at least he recommended starting another thread for fork-specific discussions.

At least that better than saying "No ^&%$ing Way!!"

Unfortunately, I need want to point out that a similar attempt at improving the FG documentation has been recently implemented/discussed and was basically rejected, I suggest to read the following threads for some additional background info:

http://www.mail-archive.com/flightgear- ... 28077.html
http://www.mail-archive.com/flightgear- ... 33665.html
http://www.mail-archive.com/flightgear- ... 36145.html

So there are clearly people interested in working on the docs, however, successful collaboration seems currently hard to achieve, so you should be aware of these challenges.

It's been my experience that "resistance" to suggestions like that usually stem from suggestions of the form: "I'd really like [such and so] done THIS way - do you mind taking on that additional huge responsibility along with the other 90,000 things you're doing?"

IMHO, if you want it, you gotta be willing to own it.

But you should be on the safe side by coordinating everything with Stuart, who is not only the maintainer of the manual, but who also has commit access so that he can apply changes meanwhile. In addition, he's a FG core developer, too.

He has already PM'd me on just that topic, so we're pretty much locked, loaded, and as soon as Thanksgiving is behind me, I'll flip off the safety and see how close to High Expert I can get.

The fact that he's "core" on the DEV list is premium! This way he can help give me code-based insights as to what is happening so that I can help improve the manual therewith.

PS: If you are serious about contributing, make sure to also read: viewtopic.php?f=42&t=15267

Thanks for the tip(s), along with all the other tips, and references you've given me. It looks like I'm going to have a full plate in front of me, just getting to the airport, forget about filing the flight-plan!

Note:
From Dec 1st to Jan 9th, I will be in Europe, spoiling the grand-children over the holidays. If I seem to fade somewhat during that time, it's not for a lack of desire. It's just hard to type with a four year old and a two year old climbing all over you! :wink:

What say ye?

Jim (JR)
What say ye?

Jim (JR)

Some see things as they are, and ask "Why?"
I dream things that never were, and ask "Why Not".

Robert F. Kennedy

“Impossible” is only found in the dictionary of a fool.
Old Chinese Proverb
jharris1993
 
Posts: 154
Joined: Sun Nov 18, 2012 10:20 pm
Location: Worcester, MA. / Moscow, Russia
Callsign: $%^&ing Idiot!
Version: Whatever..
OS: Win-10/ Linux MInt

Re: Setting up and coordinating Documentaton efforts?

Postby Hooray » Thu Nov 22, 2012 8:50 pm

Don't worry about disappearing for a while ... it's a normal "modus operandi" here. We all have other obligations and a real life.

It's been my experience that "resistance" to suggestions like that usually stem from suggestions of the form: "I'd really like [such and so] done THIS way - do you mind taking on that additional huge responsibility along with the other 90,000 things you're doing?"

IMHO, if you want it, you gotta be willing to own it.


This is certainly true, but keep in mind that other people have made similar offers to implement certain changes (including myself) and even stepped up and prototyped something, which ended up not being adopted/integrated (yet).
Such as for example jomo's work at: http://www.emmerich-j.de/HB/EN/Start.html
This must have been a lot of work, and it's a pity ...
Such issues can be hopefully prevented by coordinating things a little more.
You are certainly on the right track by talking to Stuart directly

The fact that he's "core" on the DEV list is premium! This way he can help give me code-based insights as to what is happening so that I can help improve the manual therewith.


It is my understanding that we don't currently have a dedicated manual for contributors/developers, especially those interested in contributing to the coding side of things.
Some of us have been trying to use the wiki to add related articles: http://wiki.flightgear.org/Category:Cor ... umentation
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 12707
Joined: Tue Mar 25, 2008 9:40 am
Pronouns: THOU

Re: Setting up and coordinating Documentaton efforts?

Postby jharris1993 » Thu Nov 22, 2012 9:17 pm

jharris1993 wrote in Thu Nov 22, 2012 8:09 pm:Stuart doesn't seem to be that far away from this, at least he recommended starting another thread for fork-specific discussions.

Done! You can find the new discussion thread here: http://flightgear.org/forums/viewtopic.php?f=72&t=18371

What say ye?

Jim (JR)[/quote]
What say ye?

Jim (JR)

Some see things as they are, and ask "Why?"
I dream things that never were, and ask "Why Not".

Robert F. Kennedy

“Impossible” is only found in the dictionary of a fool.
Old Chinese Proverb
jharris1993
 
Posts: 154
Joined: Sun Nov 18, 2012 10:20 pm
Location: Worcester, MA. / Moscow, Russia
Callsign: $%^&ing Idiot!
Version: Whatever..
OS: Win-10/ Linux MInt

Re: Setting up and coordinating Documentaton efforts?

Postby jharris1993 » Thu Nov 22, 2012 9:24 pm

Hooray wrote in Thu Nov 22, 2012 8:50 pm:
The fact that he's "core" on the DEV list is premium! This way he can help give me code-based insights as to what is happening so that I can help improve the manual therewith.


It is my understanding that we don't currently have a dedicated manual for contributors/developers, especially those interested in contributing to the coding side of things.
Some of us have been trying to use the wiki to add related articles: http://wiki.flightgear.org/Category:Cor ... umentation

Sorry, I did not communicate well.

What I meant is that sometimes there are interesting, and perhaps important, software twists that would not normally make it into the stock autogen'd user manual. But with him being on the dev core team as well - we can work on getting that kind of information out to the user base.

What say ye?

Jim (JR)
What say ye?

Jim (JR)

Some see things as they are, and ask "Why?"
I dream things that never were, and ask "Why Not".

Robert F. Kennedy

“Impossible” is only found in the dictionary of a fool.
Old Chinese Proverb
jharris1993
 
Posts: 154
Joined: Sun Nov 18, 2012 10:20 pm
Location: Worcester, MA. / Moscow, Russia
Callsign: $%^&ing Idiot!
Version: Whatever..
OS: Win-10/ Linux MInt

Previous

Return to Documentation

Who is online

Users browsing this forum: No registered users and 2 guests