Board index FlightGear Development Documentation

Flightplan Wiki documentation, anyone can assist?

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

Flightplan Wiki documentation, anyone can assist?

Postby Necolatis » Fri Aug 25, 2017 2:55 am

I stumbled upon this page:

http://wiki.flightgear.org/Nasal_Flightplan

Looks very promising, only its half done.
I am no expert in reading FG C++ code, and the wiki page needs updating with at least these things:

What is and how to use:
RouteRestriction
legs
flightplan-delegate
procedure

And also what is the number of arguments and uses of all the flightplan methods?

And how to replace whats in a route-manager with another flightplan? (I am planning to have 6 different routes available in an aircraft, and need to switch between which is active, howto?)

So I am asking for some help to update that wiki page. From either someone who knows stuff, or someone who is good at reading the code.
"Airplane travel is nature's way of making you look like your passport photo."
— Al Gore


Hangar: https://sites.google.com/site/fghangar/
User avatar
Necolatis
 
Posts: 1870
Joined: Mon Oct 29, 2012 12:40 am
Location: EKOD
Callsign: Leto
IRC name: Neco
Version: 2018.2.2
OS: Windows 10 Pro

Re: Flightplan Wiki documentation, anyone can assist?

Postby Johan G » Sat Aug 26, 2017 12:26 pm

Could you for now add a note about that on the discussion page of that article.
Low-level flying — It's all fun and games till someone looses an engine. (Paraphrased from a YouTube video)
Improving the Dassault Mirage F1 (Wiki, Forum, GitLab. Work in slow progress)
Johan G
Moderator
 
Posts: 5292
Joined: Fri Aug 06, 2010 5:33 pm
Location: Sweden
Callsign: SE-JG
IRC name: Johan_G
Version: 3.0.0
OS: Windows 7, 32 bit

Re: Flightplan Wiki documentation, anyone can assist?

Postby Hooray » Sat Aug 26, 2017 5:51 pm

That's actually a long-standing issue, core developers adding all sorts of neat features without documenting such additions - for some time now it's been "en vogue" to go out and claim that this would be due to "the state of the wiki" and quotes being used there in many articles - however, I'd argue that the latter is a symptom of the former been a long-standing practice unfortunately. As a matter of fact, features that are documented using dedicated articles don't usually have "quote-heavy" counterparts or additions at all.
Besides, some core developers have repeatedly stated that they simply refuse to use the forum or the wiki altogether - however, once you look at the history of the project, you'll realize that for most of the time, the project didn't have a forum or a wiki, and still former core developers would simply document their additions in the form of dedicated docs committed to $FG_ROOT/Docs and/or dedicated *.README files there.

Which is to say that the relationship between using or not using the wiki and quoting on the wiki has little, if anything, to do with the general lack of documentation for these features (outside the forum/wiki), i.e. there is no excuse not to document these additions, and certainly not due to wiki articles based on quotes trying to fill the very gap created by undocumented features.

In general, my suggestion would be to review the history of the wiki articles and commits/source files in questions and try to get in touch with the corresponding folks who committed those features.
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: 11163
Joined: Tue Mar 25, 2008 8:40 am

Re: Flightplan Wiki documentation, anyone can assist?

Postby Necolatis » Mon Aug 28, 2017 9:03 am

Thank for you reply Hooray.

Hooray wrote in Sat Aug 26, 2017 5:51 pm:for some time now it's been "en vogue" to go out and claim that this would be due to "the state of the wiki" and quotes being used there in many articles - however, I'd argue that the latter is a symptom of the former been a long-standing practice unfortunately. As a matter of fact, features that are documented using dedicated articles don't usually have "quote-heavy" counterparts or additions at all.


Well for most of the time the quotes don't bother me, especially if its in articles that discusses planned features anyway.

But some articles like http://wiki.flightgear.org/Particle_system I see it as a irritation. I have to scroll half the page down to get to the meat, which is how to use the particle system.

I don't mean this to bash on you, I know you have made lots of helpful documentation in the wiki, its just that sometimes, those quotes stand in the way of a tidy page of information. At the very least on such pages, the quotes ought to be at the bottom I think, or maybe even on the talk or own page, since they mostly discuss a future particle system. When looking up such a page, I really in 97% of the time, just want to know how to use current system, not read about whats in the pipeline for next system. The quotes about flaws in current system is relevant of course, but they still could be at bottom.
"Airplane travel is nature's way of making you look like your passport photo."
— Al Gore


Hangar: https://sites.google.com/site/fghangar/
User avatar
Necolatis
 
Posts: 1870
Joined: Mon Oct 29, 2012 12:40 am
Location: EKOD
Callsign: Leto
IRC name: Neco
Version: 2018.2.2
OS: Windows 10 Pro

Re: Flightplan Wiki documentation, anyone can assist?

Postby Hooray » Tue Aug 29, 2017 4:58 pm

Like I said a few days ago, I don't really disagree with the assertion that these quotes can be very confusing, and I also agree with bugman's statement on the devel list that they often "break" the logic of the article. I myself find some quote-based articles extremely irritating, too.

The point being that they should be easy to find if/when someone comes around to be bothered enough to take the time to incorporate/restructure relevant contents.

However, quotes are really just a symptom of a much deeper problem: core developers hardly documenting major changes, or not even documenting their work at all, considering it sufficient to tell others "just read the source". What is added to the wiki is usually sufficiently relevant to be added - it goes without question that the "format" is usually inappropriate, but it's still often better than just telling people "search the archives" or " read the code".

Equally, repeatedly stating, in public or not, that major contributors to the project would no longer edit the wiki due to such additions is not only pathetic, but also empowering the very people that they disagree with, for all the wrong reasons - just imagine for a second how this project would "work" if people (and even moreso, core developers) stopped contributing merely on the grounds of disagreeing with the statements, or wiki additions and forum postings that another user is making.

I can only reiterate my previous point: I am not as involved in FG matters these day, I fully acknowledge that "cquotes" are unfortunate for a variety of reasons, however for quite a while, the corresponding addon has been changed to create wikimedia references instead, which are much less obnoxious - besides, the script is also using a simple regex-based search/replace helper to turn 1st person speech into 3rd person.

Meanwhile, there is a growing number of "ref"-based articles, which seem to work out just fine, especially in comparison to quote-based articles:

http://wiki.flightgear.org/High-Level_Architecture
http://wiki.flightgear.org/FlightGear_Qt_launcher
http://wiki.flightgear.org/Canvas_Conce ... troduction
http://wiki.flightgear.org/Traffic_Shader
http://wiki.flightgear.org/Howto:Using_ ... FlightGear
http://wiki.flightgear.org/Scripted_AI_Objects

Sometimes, these don't necessarily represent acctual features, but ideas that some people working on. Thus, it does make sense to provide a broad overview, including pointers to the original discussions/postings. Even if only to make the point, that some developments have become known for being a "pie-in-the-sky" reputation by other senior contributors. We've seen that being the case when the Qt5/PUI vs. Canvas debate took place, or when it was en vogue to discuss replacing Nasal using Python - these, too, were interesting debates, and we cannot possibly expect people to read up on all the nitty gritty details of what's been said, or who said something.

http://wiki.flightgear.org/FGTraffic

However, comparing this to the FGPythonSys article, it's actually not in such a bad shape, because quoting makes it much more obvious who made a certain statement: http://wiki.flightgear.org/FGPythonSys


For instance, the other article created in response to this debate is this one, which is getting by with using primarily references: http://wiki.flightgear.org/Modernizing_ ... _Scripting


All that being said, I do agree that we could introduce a dedicated section for quotes, and that we could also add a template to "veto", which is to say that articles that have an active maintainer, i.e. won't receive any quotes (I could trivially add a blacklist to the script to stop automated additions).

Finally, regarding bugman's statement on the devel list that reversions would cause quote/ref additions to stop, that is actually a little misleading: the script does not even look at the editing history of the article, and neither do I usually - if I didn't undo a reversion, it's usually because someone (i.e. bugman or Stuart) took the time to rewrite the quote/ref properly, or moved the contents to a more appropriate place - apart from that I may have simply missed it.

Speaking in general, I don't usually add quotes to articles covering features/developments whose documentation I consider actively maintained (no matter if that means dedicated README.foo files, wiki articles or whatever else).

I think Thorsten pointed out on several ocassions that he usually does not want to see quotes added to his articles, and I usually respect that - obviously, I would revisit that decision if Thorsten should take a hiatus, but any of his work should be discussed on the forum/devel list in some significant way. Equally, I would also ignore a "blacklist" if I should get the impression that relevant contents, and major changes, don't make it back into the docs.

Either way, making your, or really anyone's, contributions and involvement depend on the actions or words of a single entity, user, contributor is not just pathetic and childish, it is also putting a severe blow to the project as a whole.

Just imagine for a second that my goal would be to make core developers not use the and not use the wiki using whatever works best, and now go figure ... :lol:

Again, my offer is to modify the script to ignore blacklisted articles (it is using keywords per article to look up relevant articles), and to also use a dedicated section (or the talk page). However, truth being told, we are primarily talking about articles with quotes added by the old system, the newer one will by default only add <ref> tags, which are much less obnoxious.
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: 11163
Joined: Tue Mar 25, 2008 8:40 am


Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest