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.

Re: quoting on the wiki

Postby Hooray » Wed Mar 23, 2016 1:43 pm

The Phi article is looking much better already, thanks for doing this.
I agree, that it would be a good idea to maintain at least the references (pointers) to the original discussions that you are/were using to come up with the corresponding contents.
In general, you will also find plenty of other relevant contents in the archives, including even screenshots and youtube videos - for instance, by looking through Torsten's original announcement at: viewtopic.php?f=6&t=25482

Note that "mongoose" is another relevant search term for the forum/devel-ist archives.
I would also suggest to search the the devel list for "Phi" specifically and see if you can come up with other useful information that should be added.

PS: I am glad that you figured out that referring back to the original discussions via quotes actually CAN be useful to help create/update new articles. That really was/is the sole point of articles primarily based on such "quotes" - they're intended to be an interim thing until we come up with something better
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: 11287
Joined: Tue Mar 25, 2008 8:40 am

Re: quoting on the wiki

Postby wkitty42 » Wed Mar 23, 2016 4:13 pm

Hooray wrote in Wed Mar 23, 2016 1:43 pm:PS: I am glad that you figured out that referring back to the original discussions via quotes actually CAN be useful to help create/update new articles. That really was/is the sole point of articles primarily based on such "quotes" - they're intended to be an interim thing until we come up with something better

what i don't understand is what is wrong with going ahead and starting to write that "something better"? start writing it and then let it be expanded and corrected... seems that it would take the same amount of time as it does to collect quotes and make the effort of posting them... so why not put the time to better use instead of collecting quotes do the initial writing?
"You get more air close to the ground," said Angalo. "I read that in a book. You get lots of air low down, and not much when you go up."
"Why not?" said Gurder.
"Dunno. It's frightened of heights, I guess."
User avatar
wkitty42
 
Posts: 4970
Joined: Fri Feb 20, 2015 3:46 pm
Location: central NC, USA
Callsign: wk42
Version: git next
OS: Kubuntu 14.04.5

Re: quoting on the wiki

Postby Hooray » Wed Mar 23, 2016 4:33 pm

Indeed, that's a point previously made by others (see Thorsten's and Richard's comments above) - however, like Richard pointed out already, it's also a pain/gain thing, as well as a matter of time required to do that.

As I explained previousyly, locating and creating quotes is largely automated using a bit of JavaScript code - for instance, it takes roughly 60 seconds to update something like the HLA article by adding relevant quotes extracted from postings made by Stuart, James and/or Mathias - writing contents from scratch takes much more time.
However, what works reasonably well is "de-quoting", i.e. changing first person speech to 3rd person and removing the quotation style, so that only the ref part remains.

I think you are only likely to appreciate the "usefulness" of having collections of relevant quotes once you are interested in the corresponding and once you have helped update/rewrite the article.

As far as I can tell, the main irritation caused by those quotes is their format/appearance - many other articles consist primarily of quotes, but aren't causing much/any irritation at all - maybe the cquotes script is just making it too obvious where contents are coming from.

However, you are obviously invited to give it a go and see if quotes are helpful to update/create articles, let us know if you need any help with that. I think jaxsin's recent edits, and especially the Phi related changes, are rather compelling, and the whole article could quickly grow to become really useful.
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: 11287
Joined: Tue Mar 25, 2008 8:40 am

Re: quoting on the wiki

Postby Thorsten » Wed Mar 23, 2016 4:57 pm

As far as I can tell, the main irritation caused by those quotes is their format/appearance


As has been pointed out by several people, it's the lack of context and coherence which is the problem rather than their appearance. And also signal/noise is poor - in properly writing the Earthview article the word count got down by a factor 3-4 just by removing redundant information.
Thorsten
 
Posts: 10167
Joined: Mon Nov 02, 2009 8:33 am

Re: quoting on the wiki

Postby Hooray » Wed Mar 23, 2016 7:40 pm

I am aware of this particular argument, and I don't even necessarily disagree with it - but it is only fair to point out that other articles are suffering from pretty much the same problem, including those based on quotes that are simply not attributed properly, so the cquotes style/formatting just makes the problem more obvious, while also linking it all back to a single template/use-case (and often contributor).

Regarding the recent Phi/EarthView edits, I am grateful for the corresponding work, and while your perspective may differ (because you are the EarthView developer), jaxsin stated already that Phi related quotes were indeed helpful when de-quoting/rewriting the article - and quite frankly, I would prefer having redundant information (which can be easily identified/removed) rather than missing certain information.

If anything, redundant quotes are symptomatic for the way the corresponding documentation was severely lacking, so that the person quoted felt the need to reiterate certain points, which got added "verbatim" without any proper review/down-stripping involved.

Anyway, this is not intended to be an argument - like I said, regular contributors are unlikely to appreciate the benefits of having collections of quotes in the wiki, while others may benefit from such information, especially to bootstrap new articles - without having to be spoon-fed by the original developer/s.

In the case of the EarthView article that didn't quite work out, because its original developer ended up rewriting the corresponding article - however, it seems, that in the case of the Phi article, this is in the process of working out quite well - despite its developer not being supportive of the corresponding degree of Phi related quoting in the wiki.

Like Richard said, it's a chicken and egg thing - most of these quotes would be redundant once features are better documented, absent that, they're really just symptomatic for the disparity between ongoing development and documentation efforts (which isn't such a bad thing once you think about it, in fact, the opposite would be worse for the project)
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: 11287
Joined: Tue Mar 25, 2008 8:40 am

Re: quoting on the wiki

Postby legoboyvdlp » Wed Mar 23, 2016 9:23 pm

I just started to work on this; classified some as not done and did two
User avatar
legoboyvdlp
 
Posts: 6154
Joined: Sat Jul 26, 2014 1:28 am
Callsign: YV-LEGO
Version: 2018.3.1
OS: Windows 10 HP

Re: quoting on the wiki

Postby Hooray » Wed Mar 23, 2016 9:28 pm

Yes, I noticed - thanks for getting involved to help improve the situation rather than just talking down on the quality of such wiki articles.
Like you mentioned, some articles don't much in terms of attention, i.e. the vendors stuff just contains quotes to make a point (FPS pro scam).
Other articles should be relatively simple to fix up via simple de-quoting, i.e. removing the template call and just leaving the ref part in it, while changing first person speech to 3rd person (for starters)
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: 11287
Joined: Tue Mar 25, 2008 8:40 am

Previous

Return to Documentation

Who is online

Users browsing this forum: No registered users and 0 guests