FlightGear wiki:Instant-Refs: Difference between revisions

Jump to navigation Jump to search

FlightGear wiki:Instant-Refs (view source)

Revision as of 21:35, 21 December 2015

2,986 bytes added ,  21 December 2015
→‎Background
Line 28: Line 28:
This is why it is important for other developers/contributors to know who came up with a certain idea and who originally supported it, possibly months (or even years) after a discussion took place.  Good ideas should not just be preserved, but accompanied by corresponding quotes, linking back to the original discussion, so that potential contributors can make up their own minds to determine if/how they want to get involved in some effort or not.  
This is why it is important for other developers/contributors to know who came up with a certain idea and who originally supported it, possibly months (or even years) after a discussion took place.  Good ideas should not just be preserved, but accompanied by corresponding quotes, linking back to the original discussion, so that potential contributors can make up their own minds to determine if/how they want to get involved in some effort or not.  


Equally, documentation is usually lacking behind significantly - writing documentation from scatch takes even more time. However, there is often tons of useful information hidden in the archives (devel list, forum, issue tracker etc). People unfamiliar with FlightGear may however have a difficult time locating/filtering and identifying such information in a timely fashion, so that features seem basically undocumented to novice users.  
Equally, documentation is usually lacking behind significantly - writing documentation from scatch takes time. Writing good documentation takes even more time.
 
{{FGCquote
|1= The documentation is in great need of improvement. Improving the documentation would make things better in a hurry.
|2= {{cite web
  | url    = http://sourceforge.net/p/flightgear/mailman/message/15444440/
  | title  = <nowiki>[Flightgear-devel] development process (was:  chaos...)</nowiki>
  | author = <nowiki>John Denker</nowiki>
  | date  = Jul 16th, 2007
  | added  = Jul 16th, 2007
  | script_version = 0.23
  }}
}}
 
{{FGCquote
|1= there is always a need for more and better documentation and I certainly agree that FlightGear is under documented.
|2= {{cite web
  | url    = http://sourceforge.net/p/flightgear/mailman/message/27861667/
  | title  = <nowiki>Re: [Flightgear-devel] The state of things in Flight Gear</nowiki>
  | author = <nowiki>Curtis Olson</nowiki>
  | date  = Jul 27th, 2011
  | added  = Jul 27th, 2011
  | script_version = 0.23
  }}
}}
 
{{FGCquote
|1= One response to all of this that we see frequently and is greatly appreciated (!!!) is when someone comes to our project, recognies a need or lack of something (like documentation) and decides they are going to roll up their sleeves and do something about it.
|2= {{cite web
  | url    = http://sourceforge.net/p/flightgear/mailman/message/27861667/
  | title  = <nowiki>Re: [Flightgear-devel] The state of things in Flight Gear</nowiki>
  | author = <nowiki>Curtis Olson</nowiki>
  | date  = Jul 27th, 2011
  | added  = Jul 27th, 2011
  | script_version = 0.23
  }}
}}
 
{{FGCquote
|1= The lack of internal documentation is an issue for many of not most open source projects. One reason for this is that it is a big undertaking to completely document a system of the complexity of FG.
|2= {{cite web
  | url    = http://sourceforge.net/p/flightgear/mailman/message/27861562/
  | title  = <nowiki>Re: [Flightgear-devel] The state of things in Flight Gear</nowiki>
  | author = <nowiki>Hal V. Engel</nowiki>
  | date  = Jul 27th, 2011
  | added  = Jul 27th, 2011
  | script_version = 0.23
  }}
}}
 
{{FGCquote
|1= In the long run having this documentation would help the project but it is a huge undertaking. In addition, it is an undertaking that has little if any short term impact on the project which makes it even less attractive for potential contributers.
|2= {{cite web
  | url    = http://sourceforge.net/p/flightgear/mailman/message/27861562/
  | title  = <nowiki>Re: [Flightgear-devel] The state of things in Flight Gear</nowiki>
  | author = <nowiki>Hal V. Engel</nowiki>
  | date  = Jul 27th, 2011
  | added  = Jul 27th, 2011
  | script_version = 0.23
  }}
}}
 
{{FGCquote
|1= some of the worst documenters make the best programmers
|2= {{cite web
  | url    = http://sourceforge.net/p/flightgear/mailman/message/24048580/
  | title  = <nowiki>[Flightgear-users] Documentation Idea</nowiki>
  | author = <nowiki>Brian Fahrlander</nowiki>
  | date  = Nov 27th, 2009
  | added  = Nov 27th, 2009
  | script_version = 0.23
  }}
}}
 
However, there is often tons of useful information hidden in the archives (devel list, forum, issue tracker etc). People unfamiliar with FlightGear may however have a difficult time locating/filtering and identifying such information in a timely fashion, so that features seem basically undocumented to novice users.  


The Instant-Cquotes script is intended to help with this.  It also allows people to easily reuse forum or mailing list announcements in wiki articles, e.g., to update the [[Next Changelog|changelog]], [[Next newsletter|newsletter]] or the [[Release plan/Lessons learned]] page, but also to bootstrap new articles/documentation, until a dedicated rewrite/article is finished.
The Instant-Cquotes script is intended to help with this.  It also allows people to easily reuse forum or mailing list announcements in wiki articles, e.g., to update the [[Next Changelog|changelog]], [[Next newsletter|newsletter]] or the [[Release plan/Lessons learned]] page, but also to bootstrap new articles/documentation, until a dedicated rewrite/article is finished.
Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/90773"

Navigation menu