From: Peter S. <ps...@cs...> - 2010-06-13 17:46:29
|
Drew, I agree that a wiki would be useful for this, but I'll let the rest of the community chime in. Will you be at the competition in Singapore next week? If so, that would be a great time to have this conversation in real time and with all the relevant people involved... Peter > > > One question I've been pondering is whether a TeX-generated PDF is really the best medium for the bulk of the documentation > when compared to a wiki. Here are the pros of each that I've come up with. > > > > PDF > > > > * Can be printed. > > * Can be viewed offline. > > * Fidelity of vector-based diagrams. > > > > Wiki > > > > * Editing is very easy, and only a click away when reading an article. > > * Doesn't require post-edit compilation and release. > > * Doesn't require commit access to the source code to make changes to the documentation. > > * Everyone is always looking at the head version (I spent four weeks looking at an out-of-date PDF I found > online). History is one click away and bad edits can easily be rolled back. > > * Hyperlinking: within document / outside-in / inside-out. > > * In situ discussion tabs for questions and ideas that sometimes result in quality improvements. > > * More readily indexable by search engines, increasing project visibility. > > * Wiki syntax is simpler than TeX. > > * Can embed video from YouTube/vimeo/etc (I think the Wiki supports this). > > * Support for translation into multiple languages (I think the Wiki supports this). > > > > I am happy to spend a day carrying the content of the TeX files and images over to the Wiki if people agree this would be a > good thing to do. As you say, documentation does tend to lag behind development, but if a larger audience of documenters > are facilitated by a wiki, then the lag should be reduced and the quality and depth improved. > > > > Drew. > > > > --------------------------------------------------------------------------------------------------------------------------- > > From: Peter Stone <ps...@cs...> > To: Drew Noakes <dr...@dr...> > Cc: sse...@li...; sim...@li... > Sent: Mon, 14 June, 2010 2:44:06 > Subject: Re: [Sserver-three-d] Documentation and wikis > Drew, > Thank you very much for taking the time to document that. > Documentation always lags development, and having a newcomer document > difficulties at getting up to speed is always a valuble resource. > I hope the league can incorporate all of your suggestions quickly and > accurately. > Cheers, > Peter > > > > Hello all, > > > > > > > > I'm new to these lists, having only discovered the 3D Simulation League in April after visiting the Japan Open RoboCup > > event in Osaka. Since then I've spent countless hours learning what's required to make my own agent. Great fun. > > > > > > > > I found that there was some room to improve the public documentation of SimSpark and RoboCup 3D. I have made a bunch of > > edits to various wikis and would really appreciate if people more experienced that me would review them for accuracy. > > > > > > > > Firstly, the Wikipedia page RoboCup Simulation League exclusively covered the 2D sub-league. I moved that content to a > new > > page and created another for the 3D sub-league. The previous page now links to these two new pages. I also fleshed out > > the SimSpark page. > > > > > > > > * [[[[http://en.wikipedia.org/wiki/RoboCup_Simulation_League]]]] > > > > * [[[[http://en.wikipedia.org/wiki/RoboCup_2D_Soccer_Simulation_League]]]] > > > > * [[[[http://en.wikipedia.org/wiki/RoboCup_3D_Soccer_Simulation_League]]]] > > > > * [[[[http://en.wikipedia.org/wiki/SimSpark]]]] > > > > > > > > On the SimSpark wiki I created a new page devoted to agent authoring. It contains a table of open source agents and > > base-code libraries. Please add any that are missing. > > > > > > > > * [[[[http://simspark.sourceforge.net/wiki/index.php/Agents]]]] > > > > > > > > In programming my own agent, I kept a list of where the SimSpark user manual was confusing, incomplete or possibly > > wrong. There's a new section beneath the User Manual download link on the wiki that lists these points: > > > > > > > > * [[[[http://simspark.sourceforge.net/wiki/index.php/Users_Manual]]]] > > > > > > > > Please take the time to review these pages for accuracy. Please make any changes directly, or discuss ideas for > > improvement on the relevant article's discussion page. > > > > > > > > For a full list of the changes I've made (there are other minor ones not listed above), see: > > > > > > > > * [[[[http://simspark.sourceforge.net/wiki/index.php/Special:Contributions/Drewnoakes]]]] > > > > * [[[[http://en.wikipedia.org/wiki/Special:Contributions/Drewnoakes]]]] > > > > > > > > It is my hope that these additions to Wikipedia and the SimSpark wiki will help extend the reach of these great projects > as > > well as make it even easier for people to start programming their own agents. My sincere thanks to everyone who has > > contributed to SimSpark/rcssserver3d. > > > > > > > > Kind regards, > > > > > > > > Drew. > > > > > > ------------------------------------------------------------------------------ > > ThinkGeek and WIRED's GeekDad team up for the Ultimate > > GeekDad Father's Day Giveaway. ONE MASSIVE PRIZE to the > > lucky parental unit. See the prize list and enter to win: > > [[http://p.sf.net/sfu/thinkgeek-promo_______________________________________________]] > > Sserver-three-d mailing list > > [[Sse...@li...]] > > [[https://lists.sourceforge.net/lists/listinfo/sserver-three-d]] > > > |