The International Simutrans Forum

First off, for the Starter Guide documentation, I will paraphrase:
"It's the images that make the Starter Guide so large."
and
"Without images and converted to html, the Starter Guide is around 250 Kb."
Good!  Keep it in html format, as everyone has their favorite web browser available to them (or hastily is fixing theirs ).  If the pictures are so big, why are the resolutions so high?  What about cropping the image to what is really necessary?  Both of these simple, though occasionally time consuming, tasks could be applied which would be enough to get the idea across, and that really is the intent of the Starter Guide, is it not? 

Second, do NOT follow the "... For Dummies" theme for such documentation.  I found a similarly titled series for OpenGL which mentioned "Teach me like I'm a three year old."  I am neither an adolescent nor unintelligent, but I am rather insulted by the mere suggestion of such.  I am sure that the "... For Dummies" books have turned away a rather large number of people for just such a reason.  I will fully admit to being a beginner when first learning something new and untried.

Third, the F1 in game help is not helpful enough, Prissi.  It needs quite a bit of help itself, yet.  There are situations that F1 did not even have a hint of the topic, and the Starter and Reference guides were sp**** in their aid.  The railroad signals, particularly the choose signal and end of choose signal, are a particular example here; I was finally able to understand how to correctly use them after 4 months of playing (amount of available free time here).  The one graphic that was almost descriptive enough is still severely lacking. 

Sixth, the "On Mouseover" feature would be a great help, with the possibility of an option toggle for the advanced players.  Likewise, though would most likely need a trigger system or something to implement, a pop-up window stating what is missing yet for a basic transportation of goods would compliment the beginner scenarios. 

The manuals (both starter guide and reference manual) contain info about building an airport, but they don't show the reader all rules (or the possible errors). So if the player doesn't build the airport exactly as shown, it may not work for some reason.

well this is the path of the boat. It begins at the oil rig ----> then its moves to the FreightShipDock(PakSet64)-----> then I have a train move the oil to a Chemical Plant the problem is that when the boat gets to the oil rig, it won't collect any oil but a different boat at a different rig works fine

The main problem of documentation, as VS pointed out some posts ago, is that It contains a lot of big screenshots, on average one or two per page. This is good because sometimes an image is better than a thousand words, but the main disadvantage is the space it occupies. Other games have a html version, as jamespetts said, of all documentation with just plain text. Let's wait for Ormac's opinion (Master of Documentation)

What I had in mind is the following:
1) Descriptions how to compile the program (can be found in several forum topics)
2) Description of the Simutrans programming standard (there is one somewhere)
3) A small overview what each file (or set of files) is doing to get another programmer started. Should be no longer than one A4-page, if possible even shorter. There is no such thing now.
4) A collection of answers (mostly given by you as you are the expert) to to-the-point Simutrans programming questions, like the ones you've given for example isidoro and jamespetts.

What we are missing is the 3rd item. I think that might take you 30 minutes (= one day!) to accomplish. And I think, all other programmers would benefit a lot from it.

BTW, I'm trying to write a short guide to introduce people in Simutrans code. In fact, it's a compilation of a set of articles from my blog and I've to translate them, yet. Anyway, when I have time I'll send you a preview of Dive in Simutrans (that's its name)