The International Simutrans Forum

 

Author Topic: Documentation for new features  (Read 463 times)

0 Members and 1 Guest are viewing this topic.

Offline Vladki

  • Devotee
  • *
  • Posts: 3659
    • My addons, mostly roadsigns, pak128.cs
  • Languages: EN, CS
Documentation for new features
« on: January 09, 2021, 04:30:35 PM »
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.

Offline Dwachs

  • DevTeam, Coder/patcher
  • Administrator
  • *
  • Posts: 4824
  • Languages: EN, DE, AT
Re: Documentation for new features
« Reply #1 on: January 09, 2021, 04:50:31 PM »
why is this under 'Incorporatd Patches'?

Offline Vladki

  • Devotee
  • *
  • Posts: 3659
    • My addons, mostly roadsigns, pak128.cs
  • Languages: EN, CS
Re: Documentation for new features
« Reply #2 on: January 09, 2021, 04:55:25 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.

Offline Andarix

  • *
  • Posts: 226
  • Languages: de
Re: Documentation for new features
« Reply #3 on: January 09, 2021, 05:10:13 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

Online Roboron

  • Devotee
  • *
  • Posts: 213
    • Las Gal├ícticas Aventuras de Komoyo Diga
  • Languages: ES, EN
Re: Documentation for new features
« Reply #4 on: January 09, 2021, 08:54:12 PM »
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.

Offline Andarix

  • *
  • Posts: 226
  • Languages: de
Re: Documentation for new features
« Reply #5 on: January 09, 2021, 09:22:28 PM »
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.

Offline Vladki

  • Devotee
  • *
  • Posts: 3659
    • My addons, mostly roadsigns, pak128.cs
  • Languages: EN, CS
Re: Documentation for new features
« Reply #6 on: January 09, 2021, 09:57:42 PM »
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:
Quote
New 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,
Quote
from 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.

Offline Dwachs

  • DevTeam, Coder/patcher
  • Administrator
  • *
  • Posts: 4824
  • Languages: EN, DE, AT
Re: Documentation for new features
« Reply #7 on: January 10, 2021, 09:36:09 AM »
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.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 10466
  • Languages: De,EN,JP
Re: Documentation for new features
« Reply #8 on: January 10, 2021, 01:29:56 PM »
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.

Offline Vladki

  • Devotee
  • *
  • Posts: 3659
    • My addons, mostly roadsigns, pak128.cs
  • Languages: EN, CS
Re: Documentation for new features
« Reply #9 on: January 10, 2021, 05:18:15 PM »
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?