Board index Other Hangar talk

The Few, the Tired, the Open Source Coders

Talk about (almost) anything, as long as it is no serious FlightGear talk and does not fit in the other subforums.
Forum rules
Please refrain from discussing politics.

The Few, the Tired, the Open Source Coders

Postby Hooray » Wed Nov 18, 2020 2:30 pm

https://www.wired.com/story/open-source ... few-tired/
The open source movement runs on the heroic efforts of not enough people doing too much work. They need help.


While you're surfing the web, you ought to thank Jacob Thornton for making it so pretty.

He's a programmer who, along with web designer Mark Otto, created Bootstrap, free software that the pros use to make their sites look spiffy. If you've ever noticed that a lot of websites have the same big chunky buttons, or the same clean forms, that's likely because an estimated one-fifth of all websites on the planet use Bootstrap.

One reason for its spread is that Thornton and Otto made Bootstrap open source. Anyone can use it without permission, and anyone can tweak it and improve it. Thornton didn't get a salary for making Bootstrap. When he and Otto first released it, back in 2010, they had day jobs working for Twitter. But both were propelled by classic open source motivations: It was a cool challenge, it burnished their reputations, and it felt neat to help people. Plus, watching it surge in popularity—Green Day's website used it, as did Barack Obama's White House—was thrilling.

But open source success, Thornton quickly found, has a dark side...
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: The Few, the Tired, the Open Source Coders

Postby stuart » Fri Nov 20, 2020 6:34 pm

Yup, I can definitely relate to that at times, and I do a fraction of the work that James does to keep things running.

One of the very positive things to come out of the Hackathon was getting some new people onboard and involved in the core code both on the Nasal and C++ side. I'm hopeful that will turn into more people "getting their hands dirty" and fixing things.

-Stuart
G-MWLX
User avatar
stuart
Moderator
 
Posts: 1629
Joined: Wed Nov 29, 2006 10:56 am
Location: Edinburgh
Callsign: G-MWLX

Re: The Few, the Tired, the Open Source Coders

Postby CaptB » Fri Nov 20, 2020 7:14 pm

stuart wrote in Fri Nov 20, 2020 6:34 pm:I'm hopeful that will turn into more people "getting their hands dirty" and fixing things.


Glad to hear. May I add that equally important are good quality tutorials, including video and of course documentation. Sometimes I run around like a headless chicken trying to find something in the wiki, it's structure reminds me of the 80's spaghetti code.
Ongoing projects(3D modelling): A320, MD-11, A350, B767
FG767: https://fg767.wordpress.com/
CaptB
 
Posts: 685
Joined: Thu May 23, 2013 7:36 pm
Callsign: EKCH_AP
IRC name: CaptB
Version: next
OS: Xubuntu

Re: The Few, the Tired, the Open Source Coders

Postby Hooray » Fri Nov 20, 2020 8:11 pm

The wiki can be easily improved by all contributors - you can get started by proof-reading/translating or updating articles, but obviously you can also create a new portal for contents that have gone through some quality control.

Fun fact: for many years, FlightGear didn't even have an official wiki, and even when the wiki became "official" very few long-term contributors actually got involved in creating/updating and maintaining contents.

In other words, you can be the chance you want to see ;-)
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: The Few, the Tired, the Open Source Coders

Postby wkitty42 » Fri Nov 20, 2020 9:29 pm

FWIW: the worst and biggest problem with any wiki is the major lack of proper table of contents and index... no wiki that i know of autogenerates either and they really should... otherwise they're just huge piles of pages that one has to rummage through... i have that on my desk, now...
"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: 9146
Joined: Fri Feb 20, 2015 4:46 pm
Location: central NC, USA
Callsign: wk42
Version: git next
OS: Kubuntu 20.04

Re: The Few, the Tired, the Open Source Coders

Postby Johan G » Sat Nov 21, 2020 2:58 am

wkitty42 wrote in Fri Nov 20, 2020 9:29 pm:the worst and biggest problem with any wiki is the major lack of proper table of contents and index...

It is one of several reasons why I try to push people to be better at categorizing pages. IIRC there is about 100 pages with no category or no link to them. At times it seem like you practically need to have read them so you know what to search for to find them again. That or hitting the "Random page" link enough many times... :roll:

Unfortunately a lot of the time when people actually categorize pages, they take categories for tags, and spam the articles with "tags". There need to be intent and structure to it to be useful. And preferably the category names should be self explanatory even if you are relatively new to the context.
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: The Few, the Tired, the Open Source Coders

Postby Thorsten » Sat Nov 21, 2020 9:10 am

May I add that equally important are good quality tutorials, including video and of course documentation. Sometimes I run around like a headless chicken trying to find something in the wiki, it's structure reminds me of the 80's spaghetti code.


Well, no.

I used to think that and dumped lots of time into documenting things - with the only result that this was time I did not have creating things. What did not materialize was that people used this documentation.

In most cases, nobody even tried. In the cases where people were interested in the topic, it turned out that the documentation usually didn't meet their level of knowledge - for instance people without GLSL coding experience found things too technical, people with such experience found it too cumbersome to read because it explained things they already knew,... So in fact we wouldn't use just one bit of documentation but several, dependent on context.

It turned out that a much superior use of my time is to wait for people to ask a question - in this way I can simply explain what they want to know on the level they're on. Takes 5% of the time, gives a much better result.

So unless you have reason to expect you're going to explain something over and over to dozens of people, it's not a good idea to document it.
Thorsten
 
Posts: 12490
Joined: Mon Nov 02, 2009 9:33 am

Re: The Few, the Tired, the Open Source Coders

Postby wlbragg » Sat Nov 21, 2020 11:31 am

I used to think that and dumped lots of time into documenting things

The ALS documentation is invaluable to aircraft effects modelers, at least this one! The Readme Docs that ship with FGFS, the same. The novel you wrote for the Shuttle is, for those that need it, irreplaceable without becoming an astronaut and reading through volumes of technical data as you did. But also being able to ask you specifics is invaluable as well. especially if the documentation is only cliff notes or hard to locate.
So yeah, for you and while your here and available, but you can't discount the need for it, especially if you or the document creator has moved on. On the other hand, creating and providing documentation is going well above and beyond when done in the "free" mode as we do. And then I completely agree, I feel I can either create twice as much or document half as much. Especially if I need to read documentation on how to write and format that documentation. :)
Kansas and Ohio/Midwest scenery development.
KEQA, 3AU, KRCP Airport Layout
Intel i7/GeForce RTX 2070/Max-Q
User avatar
wlbragg
 
Posts: 7588
Joined: Sun Aug 26, 2012 12:31 am
Location: Kansas (Tornado Alley), USA
Callsign: WC2020
Version: next
OS: Win10/Linux/RTX 2070

Re: The Few, the Tired, the Open Source Coders

Postby wlbragg » Sat Nov 21, 2020 11:33 am

I used to think that and dumped lots of time into documenting things

The ALS documentation is invaluable to aircraft effects modelers, at least this one! The Readme Docs that ship with FGFS, the same. The novel you wrote for the Shuttle is, for those that need it, irreplaceable without becoming an astronaut and reading through volumes of technical data as you did. But also being able to ask you specifics is invaluable as well. especially if the documentation is only cliff notes or hard to locate.
So yeah, for you and while your here and available, but you can't discount the need for it, especially if you or the document creator has moved on. On the other hand, creating and providing documentation is going well above and beyond when done in the "free" mode as we do. And then I completely agree, I feel I can either create twice as much or document half as much. Especially if I need to read documentation on how to write and format that documentation. :)

p.s. Probably not said enough, the documentation you have created is so much appreciated!
Kansas and Ohio/Midwest scenery development.
KEQA, 3AU, KRCP Airport Layout
Intel i7/GeForce RTX 2070/Max-Q
User avatar
wlbragg
 
Posts: 7588
Joined: Sun Aug 26, 2012 12:31 am
Location: Kansas (Tornado Alley), USA
Callsign: WC2020
Version: next
OS: Win10/Linux/RTX 2070

Re: The Few, the Tired, the Open Source Coders

Postby Johan G » Sat Nov 21, 2020 11:44 am

CaptB wrote in Fri Nov 20, 2020 7:14 pm:May I add that equally important are good quality tutorials, including video and of course documentation.

Thorsten wrote in Sat Nov 21, 2020 9:10 am:I used to think that and dumped lots of time into documenting things - with the only result that this was time I did not have creating things. What did not materialize was that people used this documentation.

In most cases, nobody even tried.

Unfortunately very true. And seen over and over again, and pretty much everywhere in life these days. :|

Thorsten wrote in Sat Nov 21, 2020 9:10 am:[...] people without GLSL coding experience found things too technical, people with such experience found it too cumbersome to read because it explained things they already knew,... So in fact we wouldn't use just one bit of documentation but several, dependent on context.

Indeed.

Thorsten wrote in Sat Nov 21, 2020 9:10 am:[...] a much superior use of my time is to wait for people to ask a question - in this way I can simply explain what they want to know on the level they're on. Takes 5% of the time, gives a much better result.

So unless you have reason to expect you're going to explain something over and over to dozens of people, it's not a good idea to document it.

Good point. I have noted that I sometimes expand articles when looking to link to them to when questions have been asked about a subject they touch. Maybe that is the way to go?


Some more venting. Generally I find many of the writing styles* used on the wiki quite inefficient and time consuming to look for answers in. Sometimes vague or unexpected article tiles are used, far too many articles are without a lead section requiring you to skim the article wondering if it is the one that will explain what you are looking for, and some with a lead section does not really summarize the article, leaving you to do the same anyway. And then there are all those articles with no links to the from relevant articles and categories that I mentioned a few posts back. :|
____
* In plural because nobody assumes there is a style manual end even fewer looks for it. Also, I have a very distinct feeling very few people read through Help:Your first article, even if spoon fed.
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: The Few, the Tired, the Open Source Coders

Postby benih » Sat Nov 21, 2020 4:39 pm

I really do think that documentation is valuable. It’s real value comes to daylight at the moment one wants to pick up work and can refer to a documentation where he can educate himself to the point that he can start to understand internals.
That’s assuming he can’t ask the original author because he is not around anymore.
User avatar
benih
 
Posts: 1689
Joined: Tue Aug 15, 2017 10:34 am
Callsign: D-EBHX
Version: next
OS: Debian Linux 64bit

Re: The Few, the Tired, the Open Source Coders

Postby Hooray » Sat Nov 21, 2020 4:56 pm

The wiki isn't the only source of information - for many years, $FG_ROOT/Docs was the de facto source for up to date information. And that way, the people developing new features were able to add/update documentation easily.

The wiki is just one way for people to get involved, without requiring commit access, but also without having to deal with core committers, which means there's definitely a certain quality issue, but also much less of a bottleneck issue in comparison.

To be fair, for the hackathon the original idea was to team up and gather, review and update useful wiki article - but I don't think that worked out at all: http://wiki.flightgear.org/Virtual_FSwe ... ng_started
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: The Few, the Tired, the Open Source Coders

Postby Johan G » Sat Nov 21, 2020 6:51 pm

benih wrote in Sat Nov 21, 2020 4:39 pm:It’s real value comes to daylight at the moment one wants to pick up work and can refer to a documentation where he can educate himself to the point that he can start to understand internals.

That is often how I have gotten things done, but too few people are the curious kind that try look for information themselves.
benih wrote in Sat Nov 21, 2020 4:39 pm:That’s assuming he can’t ask the original author because he is not around anymore.

This is a big point, I think.
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: The Few, the Tired, the Open Source Coders

Postby tom_nl » Sun Nov 22, 2020 10:19 pm

Interesting point re:the documentation. I came back to simming recently, exclusively with flightgear. For a user that's simply going to install it on a system with one screen, plug in a joystick, and fly, the included documentation tells you all you need to know. But as we all know that's only scratching the surface of what you can do. Once you get drawn into the rabbit hole and start to make full use of the capabilities (which i'm only scratching the surface of e.g complex multi screen setups, interfacing, panel building, and so on) much of this is not fully documented, which is understandable.

Please don't take this as a criticism by any means, i'm incredibly grateful for the work that everyone does. Technical writing is a skill, and good technical documentation is hard to write - especially for complicated systems (ask me how I know this....).

With my adventures in building a panel i've learned a LOT over the last few months, especially on the interfacing side so I'm sure I could contribute somehow. Therefore this thread has encouraged me to register an account on the wiki - hopefully any contributions I can make will be worthwhile.

Tom
tom_nl
 
Posts: 84
Joined: Tue Aug 04, 2020 11:41 am
Location: Netherlands
OS: OS X Big Sur

Re: The Few, the Tired, the Open Source Coders

Postby stuart » Sun Nov 22, 2020 10:52 pm

Hooray wrote in Sat Nov 21, 2020 4:56 pm:The wiki isn't the only source of information - for many years, $FG_ROOT/Docs was the de facto source for up to date information....
To be fair, for the hackathon the original idea was to team up and gather, review and update useful wiki article - but I don't think that worked out at all: http://wiki.flightgear.org/Virtual_FSwe ... ng_started


Just to close the loop on this:
* $FG_ROOT/Docs is still a good source for definitive information. Certainly I try to keep it up to date with the areas I work on. It has the big advantage of being versioned and (usually) in sync with the specific code changes. For example for scenery work it forms the "contract" as Rick likes to put it, between OSM2city and the FG core.
* Somewhat to my surprise, for the Hackathon no-one needed any help building FG or using git. download_and_compile script helped a lot here. So there was no need to write/collate additional wiki articles. During the event itself we didn't find a lack of documentation a problem.

Finally, to address the way in which this has gone off-topic somewhat: Documentation doesn't fix bugs or somehow provide the keys to creating new features. Outside of trivial cases, better documentation would not address the vast majority of cases raised on the bug tracker, and as Thorsten has pointed out above, the effort in writing that documentation is out of proportion to the benefit.

In most bugs I investigate I have to grep the codebase and do exactly the same analysis that someone with no knowledge of FlightGear has to do. I have the advantage of having the codebase already downloaded and in some cases memory of what the code looks like, and the confidence that I'll be able to work it out. None of this is rocket science or some magic that only James or myself possess, and is faster to pick up than people think.

A good example of this was in the Hackathon where one of the participants went from zero knowledge to creating trees in WS3.0 over the course of the weekend. That particular piece of rendering code is pretty complex, touches a whole host of different areas and required them to ramp up not only on how the existing scenery works but also the new WS3.0 scenery.

So don't wait for better core code documentation on the wiki: it isn't going to happen and isn't going to help. Get stuck in.

-Stuart
G-MWLX
User avatar
stuart
Moderator
 
Posts: 1629
Joined: Wed Nov 29, 2006 10:56 am
Location: Edinburgh
Callsign: G-MWLX

Next

Return to Hangar talk

Who is online

Users browsing this forum: No registered users and 2 guests