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.

Setting up and coordinating Documentaton efforts?

Postby jharris1993 » Mon Nov 19, 2012 4:51 pm

Note:
I am re-directing, (cloning!), the thread topic "Documentation" as a "Development" topic, (viewtopic.php?f=8&t=18341), to this location so that we can discuss this intelligently in the topic where it belongs. (Since the topic of the other thread has been granted by creating this sub-forum - thanks!)

stuart wrote in Mon Nov 19, 2012 1:22 pm:Hi Jim,

Welcome!

Having Documentation as a Development topic sounds like a great idea. I'll see what I can do to add it - I don't have permission myself.

I'm one of the maintainers of the official FlightGear Manual, which is distributed with each release. If you'd like to contribute to that you would be very welcome.

The source is in Latex. You can either download the source from gitorious (https://gitorious.org/fg/getstart) and compile it yourself, or just email me updates.

The other major source of documentation is the wiki (link at top of page).

-Stuart


Stuart,

Thanks! Giji has stepped in and is helping to move this along too.

Though I do a certain amount of work in Linux, (primarily file server configs, etc.), my favorite documentation tool is Word Perfect in Windows, if for no other reason than I know it well having used it for years. (. . . .and the fact that it is a pretty darn good "DTP" application doesn't hurt.) I'm not knocking LaTex, I just have not used it and, (at least for now), I would rather contribute something useful instead of banging my head against yet another writing tool.

Is there some common format that these two tools share, such as Rich Text, that we can use to collaborate effectively? (I don't think that WP can create LaTex "source" files, but I could be wrong - I'll have to go check.) It would be damn handy if I could produce output that you can import directly, and you likewise to me.

I also agree that the Flight Gear Manual is a great place for us to start. It's 99% of the way there, primarily needing updating, so this will be a good way for us to sync our efforts. We can tackle other, more daunting, projects later when we've gotten the kinks worked out.

Of course, the REAL "rock in the road" that I see is that we keep misspelling each others words. ( :lol: )

Ideas?

Thanks!

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 » Mon Nov 19, 2012 6:16 pm

there are also good LaTex editors available for Windows - you'll probably want to use a "Windows-based" editor (i.e. not just linux software ported to Windows!) that provides a true WYSIWYG experience: http://stackoverflow.com/questions/2701 ... or-windows
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 » Tue Nov 20, 2012 1:55 am

Hooray wrote in Mon Nov 19, 2012 6:16 pm:there are also good LaTex editors available for Windows - you'll probably want to use a "Windows-based" editor (i.e. not just linux software ported to Windows!) that provides a true WYSIWYG experience: http://stackoverflow.com/questions/2701 ... or-windows


I just looked at that site, and (AFAIK) all they talk about are tools that you use to write LaTex source code, and then compile it into (what you hope will become) the document you intended it to be.

IMHO, "code" based editors went the way of the Dodo back with WordStar running on CPM based S100 systems, and Word Perfect 5.1 for DOS 4.1.

The editor for the blog I write, (http://www.qatechtips.com), is a WYSIWYG editor that has both a "compose" pane, and a "html" pane. 99% of my time I spend in "compose", switching to "html" when things go awry, or when I want to implement an HTML feature that is not included in the stock toolbar - like horizontal lines, em-dashes, non-breaking hyphens or special typographical symbols.

Word Perfect's primary workspace is the "editor" window which is as pretty darn close to WYSIWYG as you can get. If you need more granular control, you can open up the "view codes" pane and actually edit the behind-the-scenes codes that make the text do what you want.

Likewise, (AFAIK), nobody but the most masochistic among us write full blown web pages in html source.

Seriously now, which would YOU rather code software in? C / C++ etc.? Or assembler, or even worse, raw binary? Of course you want the "higher level" language tool! Programming a project of any size at all in assembler is masochistic to the extreme, and trying to code in hex, is way beyond insanity! And yes, I know wherewith I speak, having done both.

(Of course, then there is programming a GE 4020 mainframe, in octal, using front-panel flip-switches, which I did during my freshman year in College. . . . :shock: <== what you look like after doing that for the last two+ hours!)

I am perfectly willing to support LaTex as the de facto source language for the FlightGear documentation, but I would really like to know if there are tools out there that I can use to concentrate on the document itself instead of the behind-the-scenes code that creates it?

Thanks!

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 » Tue Nov 20, 2012 2:00 am

Take a look at: http://www.latexeditor.org/
Image

And Lyx is also cross-platform software and also available for Windows: http://www.lyx.org/Download#toc3
Image

http://en.wikipedia.org/wiki/Comparison_of_TeX_editors

Regarding your soapbox speech, see: http://www.sciencesurvivalblog.com/tech ... mstex_2131 :D
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 » Tue Nov 20, 2012 2:27 am

p.s. . . .

Has anyone heard of BaKoMa TeX? (http://bakoma-tex.com)

Any comments, good or bad?

It's not cheap, but if it does what it claims to do, it might well be a Hot Smokin' Weapon!

Thanks again!

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 Michat » Tue Nov 20, 2012 4:08 am

Hi, my friends.

Wellcome Jim (Junior). I liked your article about your first impressions using FlightGear. It is clean and funny, loud and clear.

There is an extension : https://www.mediawiki.org/wiki/Extension:Wiki2LaTeX.

Maybe can help.
User avatar
Michat
 
Posts: 1226
Joined: Mon Jan 25, 2010 7:24 pm
Location: Spain
Version: 191b
OS: MX 21 Fluxbox oniMac

Re: Setting up and coordinating Documentaton efforts?

Postby Bomber » Wed Nov 21, 2012 9:10 am

My opinion.... Get people to contribute.. Collate the content first don't concentrate on presentation or storage or this app or the other....

Get the process of posting information that can be later strung together in a manual.
"If anyone ever tells you anything about an aeroplane which is so bloody complicated you can't understand it, take it from me - it's all balls" - R J Mitchel
Bomber
 
Posts: 1933
Joined: Fri Dec 14, 2007 8:06 pm
OS: Windows XP and 10

Re: Setting up and coordinating Documentaton efforts?

Postby Hooray » Wed Nov 21, 2012 9:20 am

Agreed 100% with Bomber (who would have thought that ...)
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 Bomber » Wed Nov 21, 2012 12:05 pm

My advise would be to use these forums in such a way as the knowledge that is here gets used with the manuals..

That way people won't keep asking the same questions, over and over...

And also accept the feedback from those that read the manual, if its not easy to understand, take their word for it.
"If anyone ever tells you anything about an aeroplane which is so bloody complicated you can't understand it, take it from me - it's all balls" - R J Mitchel
Bomber
 
Posts: 1933
Joined: Fri Dec 14, 2007 8:06 pm
OS: Windows XP and 10

Re: Setting up and coordinating Documentaton efforts?

Postby Michat » Wed Nov 21, 2012 9:59 pm

Bomber wrote in Wed Nov 21, 2012 12:05 pm:My advise would be to use these forums in such a way as the knowledge that is here gets used with the manuals..

That way people won't keep asking the same questions, over and over...

.


I'm agree. For that reason I started In 2011 an open source FlightGear Q&A free service. Still is alive, however it seems that admins have change their and mine css. For strange reasons this free service has no more than 13 users. I told about this service here and in the wiki, in order to integrate it in FG structure, but with no so much success.

I think this app can be use it for every category we need to use, from bla bla bla Q's, to the most technical deeper Answer. As I published in http://wiki.flightgear.org/FlightGear_Newsletter_July_2011. Anyway some of the answers are based on wiki info or contains hiperlinks to our wiki. But the service has itself a wiki integration.

Everybody is free to improved it, with support in different languages.

http://flightgear.shapado.com
Maybe it helps.
Last edited by Michat on Wed Nov 21, 2012 10:39 pm, edited 2 times in total.
User avatar
Michat
 
Posts: 1226
Joined: Mon Jan 25, 2010 7:24 pm
Location: Spain
Version: 191b
OS: MX 21 Fluxbox oniMac

Re: Setting up and coordinating Documentaton efforts?

Postby Hooray » Wed Nov 21, 2012 10:13 pm

Michat, don't take this personal.
This is a long-standing FG problem. It has often taken many attempts (and years) to establish new infrastructure parts.
Such as for example the wiki, the forum or the issue tracker. None of these were directly adopted.

Q&A/Knowledgebase solutions have been proposed (and even prototyped/implemented) by other users (such as ac001), but the feedback has not been too encouraging. The thing is, that you obviously need content providers - i.e. people who populate a new system and actually use it. Personally, I'm only interested in contributing to a resource that is "official", in that it's hosted at flightgear.org, so that Curt and others can help maintain it, and most importantly: regularly create backups, to ensure that contributions/data isn't lost.

I have previously contributed to a handful of other FG-related "external" websites, and most of them have disappeared over time, with contributions being lost.
Back then, Curt mentioned having mySQL related server issues so that he didn't want to host the FG wiki - this has obviously improved, since the forum and wiki are both now "officially hosted". But, personally, I am still concerned whenever I see external websites that cannot be controlled by the "core team".

This is because I just understand that most of the contributors here are likely to take their time off and disappear for months or even years (including myself). Thus, such criticial infrastructure parts (forum, wiki, issue tracker etc) must be maintained by "core people" like Curt, who have been around for many years, and who have maintained the infrastructure through all these years.

I know it's a painful process (been there, done it myself), but if you want to see something adopted, search the archives and try to reproduce exactly how a certain recently added part of our infrastructured got adopted, such as the build server, issue tracker, forum or wiki: Usually, because someone stepped up and volunteered to handle all the nitty gritty details and painful administration overhead...
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 Michat » Thu Nov 22, 2012 12:00 am

Hooray.
No problem, my friend. Its nothing personal. of course :) Your a hacker of honor and honesty in FG.

I'm totally agree with you on every point. It was hard to come here at present time. I'm also so strict and critic. Even to me nothing that is outside of terrasync exists.

I think you understand that the purposed of the site is for to show it as a demo. Due to a lack of responses in my initial proposal at forum, days after, I decide to create it. The code is available under GPL, so for that I thought it was good for FG integration. Because its a forum and wiki GPL manager.

Too far to be a programmer. I decided create it as a free demo for non commercial use that allow free hosting from the good guys of shapado.

Without doubt I can close it if doesn't nothing help.


Cheers.

I encouraged to use www.mediagoblin.org and OGG OGV for our media files because GPL r US
User avatar
Michat
 
Posts: 1226
Joined: Mon Jan 25, 2010 7:24 pm
Location: Spain
Version: 191b
OS: MX 21 Fluxbox oniMac

Re: Setting up and coordinating Documentaton efforts?

Postby Hooray » Thu Nov 22, 2012 12:23 am

actually, before you really shut it down, it would probably make sense to get in touch with other people who have previously raised similar ideas - maybe you can team up with with 2-3 other guys and create a compelling demo that can be adopted by the project and hosted at flightgear.org?

http://www.mail-archive.com/flightgear- ... 29049.html
http://www.mail-archive.com/flightgear- ... 33762.html
http://www.mail-archive.com/flightgear- ... 38397.html

2 years ago, before flightgear.org was CMS/WordPress-powered, the idea was to move the whole website to the wiki: http://www.mail-archive.com/flightgear- ... 29013.html

Bottom line being: Changes are ideally not just "suggested" but literally "made" in the sense that a compelling demo is provided and a handful of contributors are convinced to adopt a new resource and contribute to it.

You have just hit one of FG's weakest spot: coordination and organization ... so don't get frustrated, it takes time and energy to make your case. But as you can see (forum, wiki, issue tracker), good ideas eventually get recognized as such - you may just need to be patient ;-)
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 1:08 am

Michat wrote in Thu Nov 22, 2012 12:00 am:Hooray.
No problem, my friend. Its nothing personal. of course :) Your a hacker of honor and honesty in FG.

I'm totally agree with you on every point. It was hard to come here at present time. I'm also so strict and critic. Even to me nothing that is outside of terrasync exists.

I think you understand that the purposed of the site is for to show it as a demo. Due to a lack of responses in my initial proposal at forum, days after, I decide to create it. The code is available under GPL, so for that I thought it was good for FG integration. Because its a forum and wiki GPL manager.

Too far to be a programmer. I decided create it as a free demo for non commercial use that allow free hosting from the good guys of shapado.

Without doubt I can close it if doesn't nothing help.

Michat,

First:
Thank you for your kind words about my FlightGear article.

Second:
Don't be in a hurry to shut things down. Sometimes it just takes time, sometimes a LOT of time, for things like this to get noticed and get followers.

My own blog was the same way. When I started writing it, I wrote it for two reasons:
1. I thought it might help other people.
2. I wanted to write it. Even if nobody else read it, I enjoyed writing it.

When I started writing my blog, it appeared that NOBODY wanted to read it. But - since I enjoyed writing it, I continued writing articles for it. If nobody else wanted to read it, it was still fun for me to write and I wanted to continue writing for it.

Slowly, slowly, slowly, very slowly, it began to be noticed. A web-site visitor from here. A couple of visitors from somewhere else.

Then, it started getting referenced - a friend of mine cited one of my articles in a Software bug report. Someone on one of Microsoft's TechNet forums referenced an article I wrote about Outlook.

Slowly, slowly, slowly, I began to see comments added to some of the articles.

I now have a small, but loyal, following and I usually get hundreds of visitors from all over the globe each time I post a new article. I'm not as big as Wikipedia, ( :D ), but people are beginning to think that my blog is useful and more and more people are beginning to read it.

Your contribution is something I have never heard of until today - and I am still not sure what it is supposed to be, but if you remind me where it is, I will go look at it.

Be patient. Babies do not grow up over night.

What say ye?

Jim (JR)

p.s. "JR" in this case does not mean "junior", though I can understand your confusion.

Many years ago, I worked at a company that had someone else named "Jim Harris" (also my name), so there were now two of us with the same name working at the same company in the exact same building. To avoid confusion, people gave me the nickname "JR" (my middle initial is "R"), so that they could tell us apart. I have used that nickname as a part of my signature since then. :D
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 sa7k » 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
 
Posts: 380
Joined: Fri Mar 16, 2012 3:24 pm
Location: SA7K
Callsign: LV-EPM
IRC name: sa7k
Version: git
OS: debian

Next

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest