Re: [simspark-devel] [Sserver-three-d] Documentation and wikis

[Drew N. <dre...@ya...>]

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