Board index FlightGear Development Documentation

quoting on the wiki

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

quoting on the wiki

Postby Hooray » Sun Mar 20, 2016 3:58 pm

I originally wrote this as a PM, sending it to Stuart, Thorsten and others actively involved on the wiki (especially other wiki admins) - however, I ended up deleting the PM yesterday when I realized that it would make more sense to post this in public (especially because people tend to be involved at different times), so here we go:

Hoorary wrote:Hi Stuart and Thorsten (CC'ing other wiki admins), I was made aware of the ongoing discussion on the devel list regarding articles to which I added quotes and/or articles that I created from scratch that are largely based on quotes, so given that I am the main person adding quotes to wiki articles, and just to be very clear about it (assuming that you will be/have been discussing this off-list anyway):

I am not the slightest bit "attached" to any of those quotes (or even the corresponding articles) - however, quotes are just a symptom of FlightGear, and espcecially ongoing developments, being de-facto under-documented, i.e. tons of useful/helpful information hidden somewhere in the archives, inaccessible from an end-user standpoint.

Often that applies to features/developments whose original developers have taken a hiatus/backseat, so that ongoing discussions are intended to help others learning more about something without having to spend weeks searching the archives. Concerning the wiki article that Durk mentioned, that's a good example, because we've literally seen dozens of discussions on the forum/devel list, so that it simply made sense to provide a "goto place" (or even just a FAQ) for those wanting to learn more about the functionality and restrictions of the system.

Honestly, Erik and Stuart pretty much hit the nail on the head with their statements:
https://sourceforge.net/p/flightgear/ma ... /34950336/
Erik wrote:I see why he does this. And sometimes it's
nice to have the discussion available somewhere.

The way I see it he does this since he feels documentation is lacking
and he adds the bits to be replaced with something more useful in the
future.

It's not the best way of documenting things by far, but it is slightly
better than nothing I guess.


Still, quotes are ugly, and I agree with that very much. I have been discussing with others to change their appearance and to rewrite them automatically using the piece of code that is currently used to create them automatically (Instant Cquotes).

However, quoting remains an extremely powerful, and a really straightforward, way to bootstrap new articles/documentation, and even features that materialize over time (see below for more on that).

I think some of you (e.g. Stuart, Erik, TheTom) may be more aware of that than most others are, e.g. because Stuart actually bothered to help rewrite the HLA article on the wiki containing tons of quotes. Most others do not bother to do that, i.e. to actually document their ongoing efforts.

Apart from that, that's the whole point of having "quotes" on the wiki: bootstrapping new articles, i.e. to help document features/developments that would otherwise be undocumented.

The really power of quoting comes in when people can easily look up who's made certain statements, who's supportive of certain developments and what the context of the original discussion was. For instance, rendering related comments coming from Thorsten/Stuart are more relevant than comments I make :D

With the obvious exception of fellow wiki admins, and Stuart and Thorsten in particular, many of those who have expressed dissatisfaction with the state of affairs on the wiki, are not even regular wiki contributors (and also haven't been prior to the use of the corresponding script/technique to create/update articles, despite now making their potential involvement/contributions dependent on quoting being generally discouraged).

In fact, most others have literally taken a backseat when it comes to using the wiki to document their work/developments, and that even applies to $FG_ROOT/Docs/README.* - the legacy mechanism to document new features/developments.

In other words, this is a chicken and egg problem (totally unrelated to the wiki or my involvement there, and quoting in particular) - we would not need to have any quotes whatsoever if more people bothered to document their work, no matter the form/platform, even if people were directly contributing to the LaTex docs or $FG_ROOT/Docs.

That being said, there's a wiki template to veto the addition of quotes to certain articles (i.e. those that people actually, and actively, create/maintain and update articles), and it would be trivial to easily disable quoting template whenever that template is encountered.

However, you will find that most articles using quotes either haven't been updated in months (or years) by their creators (think Rembrandt), or were even bootstrapped using quotes (often by myself or others tracking devel list discussions, trying to perserve valuable discussions, information and pointers).

For instance, features like Phi are basically undocumented on the wiki - equally, the Qt5 launcher article on the wiki is entirely based on quotes that were rewritten over time: http://wiki.flightgear.org/Integrated_Qt5_Launcher

For the record, the Qt5 article hasn't ever been touched by the developer of the corresponding feature (Zakalawe).

Equally, the HLA article was bootstrapped, and updated, using quotes: http://wiki.flightgear.org/High-Level_Architecture

I don't like quotes, and I hate their appearance (which is trivial to change by editing a single template, which will affect all quotes/articles automatically ...)

But there's a certain loss of information involved if quotes should be removed altogether, unless people are willing to roll up their sleeves and do something about the lack of documentation, which is obviously appreciated - and the whole point of bootstrapping articles via quotes.

Which is getting us back to the points that Erik and Stuart made independently, despite certainly also disliking those quotes.

For some background, I suggest to refer to the article on the wiki documenting the script we've been using to create/add those quotes: http://wiki.flightgear.org/FlightGear_w ... nt-Cquotes

Like I mentioned previously, I won't be spending much time on FG matters anytime soon, so feel free to do with those quotes/articles whatever you think is appropriate, but I would strongly suggest to consider looking at them without looking specifically at the degree/nature of my involvement, and maybe looking at the potential merits of preserving valuable information - especially keeping in mind the typical latencies involved in contributing to FlightGear, and the shelf life of "cool" ideas.

Quite frankly, certain features we simply would not have today in FlightGear, if it was not for articles summarizing community debates/consensus and popular feature request - e.g. the Canvas system, which was basically suggested by Mathias and James in early 2008, before being prototyped by someone external/new to the project at the time, 4+ years later, based on a wiki article and the momentum it helped create/maintain: http://wiki.flightgear.org/index.php?ti ... ldid=21408

Likewise, you could say that Stuart's current HLA/AI related work is in line with the collection of long-standing discussions "quoted" at: http://wiki.flightgear.org/Decoupling_t ... _Rationale

The main difference here is that this is not using automatically-created "quotes", but manually assembled - and nobody seems to take any offense by that article apparently, probably because its appearance is not as obnoxious.

Thus, I would respectfully suggest not to underestimate the power of "aggregating" long-standing debates/discussions and presenting those on the wiki - while the style/appearance leaves a lot to be desired, that's easy to change (or move elsewhere, like Stuart suggested).

People may disagree with my persona and the degree/nature of my involvement, but once you spend 15 minutes reviewing such articles, you will see that I didn't/don't have any personal/particular agenda other than summarizing such debates, i.e. that these are actually long-standing issues that have been going on for years literally, so that it does make sense to preserve such discussions, and provide pointers.

In fact, referring to the "Decoupling AI traffic" article I mentioned before, you will find that Durk is the one primarily quoted there, and that Stuart's current HLA/AI work aligns well with his original remarks - and most people would not even be aware of that (probably including even Durk), if it wasn't for that particular article.

For two more recent examples of articles, and actual code/features. that were entirely bootstrapped using "quotes", refer to:

http://wiki.flightgear.org/Graphics_Card_Profiles
http://wiki.flightgear.org/Howto:Using_ ... r_%28IG%29

Other examples like the FGPythonSys article may seen unfortunate at best, but they still represent ongoing work, and contain tons of useful information/pointers for people wanting to get involved: http://wiki.flightgear.org/FGPythonSys

Again, there's no agenda here on my end, simply because I don't have any use for Python myself, I just took the time to document this to ensure that things will be preserved for the future.

No matter what you end up deciding here, I suggest to tread carefully with the degree of information that is currently preserved in the form of "quotes", especially if you are considering to remove them altogether, without providing a feasible replacement/alternative.

And I would particularly recommend to look at who is actually going to get involved to improve the state of affairs, rather than just those who criticize the current situation, which is really just the result of people not documenting their works - i.e. are people willing to be part of the solution or just part of the problem ?

In a perfect world, we would not need to be using quotes - or they'd just be an interim thing, until someone comes along to help rewrite such articles (like Stuart has done in the case of the HLA article, and like others are offering to do now) - but realistically, most people do not even remotely care enough about documenting their work properly (excluding obviously Thorsten and a few others, who're apparently writing at least as much documentation as code).

(feel free to discuss/forward/re-post this as you deem appropriate)

PS: Speaking for the future, and in general, just like core development matters are generally discussed on the devel list, wiki matters are generally discussed -in public- on the wiki directly, or at the very least in the Documentation sub-forum on the forum, and the corresponding feedback/opinions are weighted based on the involvement of those voicing their concerns - also not unlike core development matters I guess.
In summary, whenever someone is willing to roll up their sleeves to do something about a particular problem (e.g. getting rid of quotes), that is highly appreciated. And quite frankly, those quotes have accomplished quite something if there is a consensus to improve the state of documentation on the wiki, even if that means to get rid of quoting and to re-introduce the practice of requiring developers to document new/updated features in the form of additions to $FG_ROOT/Docs
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: quoting on the wiki

Postby Johan G » Sun Mar 20, 2016 11:09 pm

I also have mixed feelings about them, but at least sometimes see the benefit of having them there. And indeed, very rarely is no documentation better than some documentation, whatever form it may have.
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)
Some YouTube videos
Johan G
Moderator
 
Posts: 6629
Joined: Fri Aug 06, 2010 6:33 pm
Location: Sweden
Callsign: SE-JG
IRC name: Johan_G
Version: 2020.3.4
OS: Windows 10, 64 bit

Re: quoting on the wiki

Postby Hooray » Sun Mar 20, 2016 11:34 pm

I am the first to admit that it would be great to replace/rewrite all quotes and/or to get rid of articles with excessive quoting entirely, i.e. those that are >= 80% quotes for the time being.
On the other hand, the main issue seems to be one of styling/formatting, i.e. many other articles also consist primarily of contents copied from other sources, but are simply not attributing the source properly - in other words, changing the style/template may be one way to accomplish this, while some of the more important articles are updated to get rid of those quotes.

And like you say, many articles haven't been updated by their respective owners/developers in months or even years, so that the alternative is having no up to date documentation at all - in the context of the "Status of AI in FlightGear" article, that one was specifically created in response to dozens of discussions we've seen on the forum/devel list at a time when there was obviously huge interest, but not much going on in terms of actual development, or even just updated documentation.

But again, quotes are not a replacement for documentation - they're just intended to help bootstrapping new articles, or to get people started doing something, especially those not familiar with certain topics/features or other internals of the project. But I am definitely not attached to any of those quotes or the articles using them.

All the people who have expressed a desire not to have quotes in "their" pages/articles are voicing valid concerns, as long as they're actually around to help maintain/update the corresponding documentation - but once there's a disparity between what's available in terms of information in the archives, and what's "documented" elsewhere, we're losing information if we don't preserve that in /some/ way.

Equally, it really does matter who makes certain statements - which is kinda supported by Durk's notion of "a random developer" in his original posting.

Like Thorsten said, getting rid of quotes in actively maintained articles should be relatively straightforward - but I do maintain the standpoint that other articles (e.g. those that are largely collection of quotes) may have merits that may not be obvious to most people, which is in line with the comments Erik and Stuart made in response to removing quotes entirely.

Personally, I don't think we need to maintain quotes inevitably - maintaining the <ref/> part could suffice just as well, as long as the surrounding context is maintained.

But like I said, I am not attached to those quotes, and I am certainly not going to fight anybody who's willing to help update/improve the wiki accordingly - I would merely suggest to reconsider the alternatives we have - especially referring to articles that don't have any de-facto maintainers, i.e. people who consider themselves responsible for updating such articles.

And in all fairness, it is far too easy to disagree with quotes/quoting in general - but please also look at the background/history of those expressing their dissatisfaction.

For instance, Thorsten told me several times in private that he didn't appreciate quotes being added to "his" articles, and that he'll gladly take the time to update/maintain his own articles separately, i.e. he explicitly told me not to add quotes to "his" articles, and I think I actually honored that wish.

However, there are articles that don't have any de-facto "owners", but which still serve a certain purpose - e.g.:

http://wiki.flightgear.org/CompositeViewer_Support
http://wiki.flightgear.org/Particle_system#Known_Issues

I think it is only fair to point out that Thorsten did send this link to the devel list in order to make his case a few weeks ago: https://sourceforge.net/p/flightgear/ma ... /34850093/

Equally, other long-term contributors have used such "articles", to raise certain issues without having to write stuff from scratch - e.g.: https://sourceforge.net/p/jsbsim/mailma ... /34727642/

And that also applies to other core developers, including those who are now stating that they prefer not to be quoted elsewhere.

Note that I am not "attacking" any of the people here, just making the point that this is at least a two-edged sword - and that the opinion people hold depends greatly on whether they find those quotes useful or not, and that this may change over time.

I hope this helps put things into perspective, regardless of who's adding those quotes.
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: quoting on the wiki

Postby Thorsten » Mon Mar 21, 2016 7:04 am

Let's put it like this: It certainly costs some fraction of time to locate the quotes and to make them appear on the wiki. If half of that time would be allocated not to add more of the same and rather to edit the existing quotes into a coherent whole message, the documentation would be much better.

It's not that the material is generally worthless - it's a question of signal to noise.
Thorsten
 
Posts: 12490
Joined: Mon Nov 02, 2009 9:33 am

Re: quoting on the wiki

Postby Richard » Mon Mar 21, 2016 8:38 am

The basic problem is not the quotes it is the lack of decent documentation that would make the quotes redundant. There are areas that are well documented (such as ALS), however where there isn't documentation I've previously found quotes useful.

Often when a question is posted to the list the answer is to refer back to the archive. Generally searching the archive for specifics often requires prior knowledge of what you're looking for on a technical rather than functional level and whilst I'm sure that I'm in a minority by searching the archive first I can definitely say that the the quotes have helped me find the relevant discussion on a per subject basis.

I agree with Thorsten that the time finding the quotes could be spent writing the documentation; however this assumes a certain level of detailed subject knowledge that may not be present. I also see that most of the pages could be edited to distill down to what is actually relevant and accurate. Equally I'm not in a position to make any requests about how anyone spends their contributed time.

I prefer to see all of the quotes collected together into one place on the given page, possibly in a previous discussions section, with possibly a simple suggestion/disclaimer that it is essential to read the discussions to gain the context of the quote.

Quotes are considerably better than nothing, and usually a poor substitute for good documentation. I'm grateful for whoever has spent the time doing this as it has helped me.

What I've not seen, and hope never to see is good documentation having irrelevant quotes inserted at the top or out of context.
Richard
 
Posts: 810
Joined: Sun Nov 02, 2014 11:17 pm
Version: Git
OS: Win10

Re: quoting on the wiki

Postby Hooray » Mon Mar 21, 2016 10:56 am

Thanks Thorsten. And Richard thank you very much for writing such a detailed and thoughtful response.
I wholeheartedly agree with everything both of you said here, I have always considered such quotes to be a "compromise", i.e. the foundation for bootstrapping/writing new documentation, rather than a replacement for it.

In some cases, that has worked out exceptionally well, in others, it frankly hasn't at all. But at the end of the day, it's also a pain/gain matter - I could obviously rewrite many quotes and turn them into articles (in fact, usually "de-quoting" helps tremendously), but that will cost tons of time that could be spent differently.

But like I said, I am not the slightest bit attached to any of those quotes, and certainly not their appearance. I do appreciate Richard's suggestion to establish a more standard structure and use that in the future, I hope that Johan, bugman or Gijs have ideas on how to accomplish that in a sane way - and I am definitely volunteering to rework such articles accordingly. In fact, I do think, that we already have quite a few articles that are using a similar structure with paragraphs named "Related discussions".

Concerning the argument that the "time spent finding the quotes could be spent writing better documentation", that's a valid point - but actually the process is fairly automated meanwhile, the script on the wiki is just the browser-side extension for adding quotes, there's another script that will look up/cross-reference related discussions by using the corresponding keywords.
Otherwise, it would frankly be impossible to come up with so many relevant discussions spread over such long periods - in fact, the script will search 5 different mailing list archives using the corresponding keywords.

And like Richard said, a number of people do appreciate such quotes, i.e. because they can look up the context and original posters much more easily.
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: quoting on the wiki

Postby jaxsin » Mon Mar 21, 2016 11:30 am

I'm going out on a limb here and make a really short and concise argument. Because it doesn't take a well thought out argument.

In fact, I do think, that we already have quite a few articles that are using a similar structure with paragraphs named "Related discussions"


discussions are just that, they are not any form of documentation. Merely ideas being thrown out there to, as you so delicately put it, bootstrapping progress. To expand upon this slightly, while I was looking for information in the wiki I found the quoting to be most unhelpful. What was current? What was stable and in-sim ready to be used? What was a wet dream and is now a defunct idea? The quoting answered none of that and essentially drove me away from even looking at the wiki for understanding.

But I digress, there is a tab page on the wiki labeled discussions for a reason. This, if any place, is the appropriate place for said quoting. While there is proper documentation on the wiki for some subjects, all the quoting should be left out of the those main articles. We can reference the mailing list and forums and make the pages better and function better for those reading them. My opinion, means nothing, but you got it.
jaxsin
 
Posts: 395
Joined: Mon Dec 28, 2015 4:54 pm

Re: quoting on the wiki

Postby Hooray » Mon Mar 21, 2016 11:58 am

Thanks for your feedback/opinion.
To answer your question, whether something is "current", can be usually determined by looking at the date of the quote, whether something fits the corresponding context, can be determined by looking up the original discussion (via the ref link). Whether something is "relevant" can be determined by looking at the person quoted, i.e. that person's track record.

Your point about "discussions vs. documentation" is well taken, and I don't disagree with that - but the fact is that we, as a community, tend to have lots of discussions (or even debates) that end up "documenting" otherwise undocumented features/functionality, so it goes without saying that following such discussions ends up having a certain informational value.

Usually, it's just the style/format that makes such discussions unsuitable for being directly reuse "as" documentation. The obnoxious cquotes format we're using on the wiki just makes that much more obvious - as you may not know, there are literally dozens of articles that primarily consist of postings quoted verbatim, without any proper attribution, and these don't get challenged at all.

So it definitely also is a matter of format/style, quality (or lack of thereof) does not seem to be the primary issue here (unfortunately).

Anyway, I don't disagree that the potential merits of certain "articles" (=collection of quotes) depends hugely on your own background/interests - i.e. what you want to do with FlightGear.

In fact, I don't need certain collections of quotes at all, I just ended up preserving useful contents - e.g. referring to the MapStructure article on the wiki, which got also bootstrapped using quotes from the forum.

If you are an end-user wanting to /use/ FlightGear, you are unlikely to benefit from quoting, except for rare cases of otherwise entirely undocumented features like Phi or the Qt5 launcher, which never ended up being documented by their respective developers.

Referring specifically to the AI article, the quotes there are only relevant for people interested in the discussions revolving around scripted AI and limitations of the current system - as such, they're really aimed at the kind of contributor/developer wanting to use/extend the system for any of the use-cases discussed there.

Back when the "Status of AI in FlightGear" collection of quotes got started, Durk wasn't around, so it made sense to preserve recurring topics and provide some kind of "FAQ".

Note that none of this is intended to sound harsh or offensive - if you are willing to help anybody clean up the corresponding wiki articles, you are obviously invited to do so - I would just suggest to closely coordinate that with the corresponding parties (e.g. Durk), and to touch articles that you are willing to help maintain/update in the future.

I am saying that specifically because given your posting above, I find it in stark contrast to Richard's and Thorsten's statement (they specifically stated that they saw the merits/relevance of having certain quotes), so that it seems problematic to have someone "peer-review" articles without that background.

Thus, my suggestion would be to work with whoever is willing to mentor you, e.g. Durk and/or Torsten to help update the corresponding articles.

However, "articles" like Status of AI in FlightGear are probably not a good starting point for you, given that they're specifically created in response to popular forum discussions - however, should you feel brave, you are obviously invited to give it a go, and while you are at it, you may find those quotes actually helpful, because people can look up the original discussions, i.e. they won't necessarily need someone to spoon-feed you if you are willing to do a bit of legwork first.
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: quoting on the wiki

Postby jaxsin » Mon Mar 21, 2016 12:27 pm

I am saying that specifically because given your posting above, I find it in stark contrast to Richard's and Thorsten's statement (they specifically stated that they saw the merits/relevance of having certain quotes), so that it seems problematic to have someone "peer-review" articles without that background.


You made a lot of assumptions in your previous post, but I will pick out the only one that should matter. Had you been paying attention you would see that I also did not discredit the idea of quoting, but the manner in which it was done. It does not help the likes of "me" at all(the end user). In fact I found the wiki quite useless when I was reading the quotes. I'm the end user that is reading your wiki and trying to make something of it. Thorsten and Richard are not looking at the wiki from my stand point and they could careless about what is contained, unless it keeps them from answering the same question about their projects in FG. Feel free to disagree Thorsten and Richard.

On top of that, now I am being told in a way that I should just avoid helping because I have a dis-pleasurable position over the quoting that I found most unhelpful from an end users prospective? Because that makes sense to do

To answer your question, whether something is "current", can be usually determined by looking at the date of the quote, whether something fits the corresponding context, can be determined by looking up the original discussion (via the ref link). Whether something is "relevant" can be determined by looking at the person quoted, i.e. that person's track record.


Let me just dispel this right now, no it did not answer any of my questions.
A wise man once said " Assumptions are the mother of all F-- up's!"

RTFM? Then give me the fine manual!
jaxsin
 
Posts: 395
Joined: Mon Dec 28, 2015 4:54 pm

Re: quoting on the wiki

Postby jaxsin » Mon Mar 21, 2016 12:33 pm

As others have said, the quoting was without a doubt of good intentions. But good intentions turn bad when it does not help but only hurts what was already in place. I totally agree with this position and it is one that ask for everyone to either improve the wiki and make it better or leave it and move on. Thorsten asked on the devel mailing list to have developers update their work in the wiki. This is the only way forward AFAIC and I have already made it clear that I would like to help. I will wait for someone that thinks I am capable of the job to contact me.
jaxsin
 
Posts: 395
Joined: Mon Dec 28, 2015 4:54 pm

Re: quoting on the wiki

Postby Hooray » Mon Mar 21, 2016 12:39 pm

Please let's at least try to keep this constructive/positive.

If you are willing to help /us/ clean up the wiki, you are invited to do so - however, be prepared to see your changes challenged if they're removing useful information.

For instance, Thorsten just finished editing a handful of his own articles and he removed quite a few quotes from those - yet, he also managed to remove helpful information, probably because he considered it irrelevant or simply self-explanatory (him being the developer of AW/ALS and EarthView, that goes without saying).

Besides, you should never make your own involvement/contributions depend on someone else (or their statements), no matter if that means getting active support or being actively discouraged.

To be fair, I understand that there's a fair bit of campaigning going on currently - but quite frankly, whenever we -as a community- are doing this sort of thing, we are empowering the very people we are disagreeing with, no matter of that means "FlightProSim", "fgmembers" or individuals like Hooray, vitos, Bomber etc

That said, I merely suggested to make sure that you are being mentored while updating articles you are taking an interest in, so that you don't up removing information that you didn't understand due to your own background. Like I said, even Thorsten himself just removed information (not quotes), that I would have kept personally.

But at the end of the day, it's his call - those are his articles, and he's actually maintaining them.
It is true that I created the EarthView "article" solely using quotes, but Richard also got a point: I am not sufficiently interested in AW/EarthView or Rembrandt to get up to speed and write the corresponding documentation from scratch, so there's that too - which is why I merely added relevant content found elsewhere.

The documentation, the wiki, and the project as a whole, would be in excellent shape if all of us were as responsive as Thorsten has been in response to the "quotes" discussion currently going - i.e. he's part of the solution rather than the problem.


PS: Thanks for clarifying your background, much appreciated!
PPS: I would suggest not to "wait" for people to contact you but to be proactive and try to do something - as you can tell by now, Thorsten never asked me to create the EarthView "article" ;-)
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: quoting on the wiki

Postby Johan G » Mon Mar 21, 2016 11:25 pm

There is now a page on the FlightGear wiki, FlightGear wiki:Quoting Guidelines (perm), discussing guidelines regarding the use of quotes on the wiki. Join the discussion.
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)
Some YouTube videos
Johan G
Moderator
 
Posts: 6629
Joined: Fri Aug 06, 2010 6:33 pm
Location: Sweden
Callsign: SE-JG
IRC name: Johan_G
Version: 2020.3.4
OS: Windows 10, 64 bit

Re: quoting on the wiki

Postby PINTO » Mon Mar 21, 2016 11:50 pm

Was really hoping that wiki page was just going to be a bunch of quotes...

Not going to argue, as it's 100% pointless to argue, but when I see an article that's all quotes, I don't read it and just close out of it.
Actively developing the MiG-21bis (github repo) (forum thread) (dev discord) (fg wiki)

http://opredflag.com is an active flightgear dogfighting community (using a system that isn’t bombable)
User avatar
PINTO
 
Posts: 966
Joined: Wed Oct 21, 2015 7:28 pm
Callsign: pinto
Version: stable
OS: Win10

Re: quoting on the wiki

Postby Hooray » Tue Mar 22, 2016 12:04 am

As has been said previously by myself and others (see above), whether quotes are considered helpful or harmful is generally a matter of your background/interests and degree of community involvement - it makes perfect sense that the typical (and actively involved) core developer doesn't see the merits of quotes, given that core developers are often the ones being quoted (or at least the ones already aware of the corresponding topic/issue).

Equally, end-users are rather unlikely to benefit from purely quote-based articles.

Thus, I think that Richard, Erik and Stuart summed up the point of having quotes rather well - but that is not to say that quotes would not be extremely unfortunate - however, please keep in mind your own background when commenting on whether quotes are generally problematic or not - frankly, if you cannot see why having articles with certain quotes /can/ be more than just a little helpful, you clearly don't belong to the target audience.

Nobody is expecting you to read quotes - the people who do have a use for them, will make up their own minds whether or not something is useful.
In general, end-users and even actively involved contributors are rather unlikely to benefit from quote-based articles, absent some corner cases like "recent" developments that haven't yet been documented by their developers (think Phi, Qt5 launcher or FGPythonSys).

In a way, this isn't unlike the FlightGear newsletter: if you are actively involved, or someone very familiar with FlightGear core development, you are unlikely to benefit from reading it at all...
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: quoting on the wiki

Postby jaxsin » Tue Mar 22, 2016 1:51 am

Believe me, I get it, documentation is very important. In fact all the open source projects I have been involved in very much stressed the importance of rtfm. When done properly it makes for easy time running helpdesk in irc channels. As it will help as a great reference to the users who stop by this forum.

But, if I am looking at the wiki as a 'noob' and expect to get something from it, I may be in for a big surprise and it may leave a bad taste in my mouth. It's just a thought because first impressions matter. Is that not the same motivation behind the graphics card automatic detection and updating of settings? To give a better default first impression to those crave the high end experience? Maybe that is the hammer on the nail head for me, it's not the quoting as I found it useful for Phi, but first impressions. Certainly that can be improved upon?

Per the wiki, I don't feel comfortable removing everything without making references to the quoted materials if it maintains with upstream design goals or current development. So unless someone has some objections, I am moving forward with what I feel I can help clean up. I follow the devel mailing list now, so I am starting to feel more comfortable with the project.
jaxsin
 
Posts: 395
Joined: Mon Dec 28, 2015 4:54 pm

Next

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest