News:

Use the "Forum Search"
It may help you to find anything in the forum ;).

Documentation for new features

Started by Vladki, January 09, 2021, 04:30:35 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

Vladki

It would be nice to have some documentation for pakset creators about the new features. Information in https://simutrans-germany.com/wiki/wiki/en_Devel_Index?structure=en_Devel_Index&page_ref_id=459 seems not updated recently. Lots of recent features are nice, but incorporated only in pak64. Like the the new tools: groundobj builder, rotate buildings, merge stops; or changes in behavior: max_speed on crossings, smoke on factories.

Would it be possible to have a sticky topic, with short reference of each new improvement that somehow affects the paksets? Pakset maintainers could then subscribe to the topic and be alerted to add new features to their pakset.

Dwachs

why is this under 'Incorporatd Patches'?
Parsley, sage, rosemary, and maggikraut.

Vladki

Quote from: Dwachs on January 09, 2021, 04:50:31 PM
why is this under 'Incorporatd Patches'?
Because I thought that such documentation should be here - documenting only incorporated things. But If you thing there is better place for that, then move it.

Andarix

Quote from: Vladki on January 09, 2021, 04:55:25 PM
Because I thought that such documentation should be here - documenting only incorporated things. But If you thing there is better place for that, then move it.

the German wiki is partially updated

example menuconf

changes for v121 and v122

Roboron

There's a Technical Documentation subforum.

Afaik, Vladki concerns are valid, I often find a lack of documentation (or outdated documentation) for Simutrans - not only for paksets creators, but also for players looking for features/help and coders looking for resources (and I say that after trying to improve some of the documentation). I feel like changes are done but often not documented/updated or documented poorly or on the wrong places.

Just impressions, not trying to tell anyone what should do. I know we are all busy, I'm the first wishing to have more time to help with this problem.

Andarix

Documentation is tedious and takes time, but it's not fun.

Which is why developers almost always put it off and then forget about it. That's what the community is for. Only they have the problem that those who know don't do it because they know. And those who don't know can't do it.

If there were more people who would work on the documentation, then there would also be a current documentation. Wikis were once invented for shared collaboration on documentation.

But even with the translation of the texts and the in-game help, Simutrans has had it for decades.

Vladki

The problem is that writing the documentation by looking at diff files is much more complicated than writing a short post at a "news/changelog" thread, in this style:
QuoteNew lists are available: list of depots and list of all vehicles (shopping catalogue). They are dialog_tool[32] and dialog_tool[33], add them to menuconf.tab in similar way as e.g. list of stops (dialog_tool[14]). Available since rXXXX
Or,
Quotefrom rYYYY the speed option on crossings forbids building the crossing on faster way than specified, instead of just slowing down the vehicles crossing the crossing. No more crossings on high-speed tracks.
Of course this is not needed for bug fixes, or improvements that do not need to be reflected in paksets.

Dwachs

There is also

https://github.com/aburch/simutrans/blob/master/simutrans/history.txt

If you have questions about particular things feel free to ask them. If there are no answers then send me a PM.
Parsley, sage, rosemary, and maggikraut.

prissi

pak64 is somewhat the official reference, as most new features (if possible) are incorporated there.

Additionally to history.txt the svn log messages gives a good hint what changed. Moreover, after incorporating a patch, sending strings to translator, and testing this with pak64, I spent already the three hours till midnight I have. So I am sorry for bad documentation. But looking at pak64 shoudl give you a good example.

Vladki

Thanks for the hints. May I ask moderator to move this to Technical documentation forum and make it sticky so that it will be easier to find later?