Help for the Help Wiki

[Westernmost]

I'm sure this has been kicked around a lot already, but my newest attempt at this begs the question again.

Is there any plan to better organize the Help Wiki for rookies so that it presents a logical journey through the system instead of leaving it to the user to hunt for needed information that may or may not be accessible if he doesn't know what to search for?

There is a nice page on downloading and "getting started." And then it leaves you sitting there, with no indication of where to go next for meaningful orientation into this amazing world you just entered. Without an opening orientation, nimrods like me get stuck and frustrated. For example, I wanted to find info on the concept of "baseboards." But without knowing it was called a "baseboard," it took me several searches to finally find the page that provided a good explanation of them. Ditto a nice, clean flowchart of the process. If you don't know what to ask for, the answers can be very hard to find.

This is in no way to knock all the work that's gone into writing the thing. I'm just saying that all this knowledge needs to be laid out in a logical order, specific to each version. That "getting started" page, for instance, does have a directory of next steps - for the 2012 version, and doesn't say so until you're there. (The fact that it reminds you that 212 had a manual didn't help the situation!)

I also gladly acknowledge the tutorials and YouTube videos that are intended to help with this. But videos have a drawback in that documentation doesn't - I can print out documentation and flip back and forth through it if I need to. Plus, if the game is already aggravating me, I really don't want to compound the stress by fighting with a video.

For sake of context, I came into this from Train Player. TP may have chintzy layout graphics and 2D only, but it has a superbly organized help section. Plus the downloads are almost instantaneous instead of dying after hours of the Download Store's blazing 4K per second rate.

I dig that even one version of Trainz would need a library of manuals to cover everything. But at least something in concise, logical, printable form would be very helpful.

 

[pware]

I agree, especially with your point "If you don't know what to ask for, the answers can be very hard to find."

From professional experience writing user documentation is a slow and difficult task. A task that is made even harder when the subject being described is current technology. Unlike history where the "facts" (names, dates, places, etc) are "fixed" and well known, the "facts" in technology can change overnight.

Each time a new version of Trainz is released (approximately every 2-3 years) much of the documentation has to be rewritten. Service Packs and Hot Fixes, which appear more frequently, often require some rewriting, but this can still be time consuming. With Trainz Plus significant new features appear approximately every quarter.

For the reasons above (plus the shear costs involved) the days of a complete printed manual with every software product are long gone.

This is where the Trainz Community has stepped in with the Trainz Wiki. In many ways community involvement is a good thing but it does leave gaps.

 

[pcas1986]

TANE was the last version of Trainz that included a manual (pdf) and even that was out of date when TANE was finally released. I remember it well since as a beta tester I read the manual from cover to cover. The last few chapters probably didn't get the attention they deserved.

There is a user guide for TS22 which is outside the Trainz WiKi that might help. See https://docs.trainzsimulator.com/docs/trs22-user-guide It's not TS19 but there would be a lot in common.

 

[pware]

Yes, even PDF based documentation is going the way of the dinosaur. While it has some obvious advantages over paper based documentation (now extinct) it still suffers from having to be redistributed after every update, which means all the users have to download the new copy into their PDF readers. And updating PDF is still not an easy task.

Web based documentation, usually HTML or Wiki (or both in the same document), is now the current "standard". It is generally easier and usually quicker to update and distribute than PDF and does not require the users to manually download the documents. My last contract (i.e. paid) documentation writing project was entirely web based.

 

[pcas1986]

...
Web based documentation, usually HTML or Wiki (or both in the same document), is now the current "standard". It is generally easier and usually quicker to update and distribute than PDF and does not require the users to manually download the documents. My last contract (i.e. paid) documentation writing project was entirely web based.

I like the context style of documentation where you can, say, right click on some menu item and be taken to an explanation of the item in question. I did some of that for Andi and PEV's AssetX before it became unsupported. Trainz does have some in the error messages on asset committal but they are not obvious.

 

[Jima5e]

On a related note, I tried using the docs at https://docs.trainzsimulator.com/getting-started today. None of the built-in links on the page worked! What's up with that?

 

[Forester1]

That's because they are internal links. Instead of an internet url they are going to "file:\\\", and that's not going to work.

 

[Dinorius_Redundicus]

The trainz Wiki is notoriously amorphous and I think the chances of it being substantially re-written are basically zero. One thing that could help enormously is a smarter search facility. Perhaps artificial intelligence could be useful in this context, since the current search function is pretty dumb.

 

[PGibbons]

This is another reason why Trainz has to be stabilised instead of continually introducing cosmetic changes which only upset existing functionality. I've always thought that the program should have never been changed to run on other platforms - just stick to Windows versions and get them working as advertised.
PG

 

[pware]

The trainz Wiki is notoriously amorphous and I think the chances of it being substantially re-written are basically zero.

I agree. The time and effort required would be prohibitive. Then add in the rapidly changing technology (S20, HD terrain, TLR, MPS are just a few recent examples) that would require almost constant updates. The latest Trainz Plus beta, for example, introduces some new features and reorganises others, all adding to the task.

 

[JCitron]

If N3V got everything to a homeostatic state where everything worked properly before bolting new features on top, we would have a chance to document functions and organize the wiki. Once the basic program is fixed, adding new features on top will be much easier to add to the wiki rather than having to go back and constantly update stuff that shouldn't need constant updating.

I know this sounds pedantic, and in some ways, I'm preaching to the choir, and I also know that to in order to stay in business, they have to keep coming up with new ways to reinvent a wheel and throw new features out faster than they can be fully tested, but it's going to get to a point where the developers are going to have to stop, look at the mess they created, and clean up what's been done.

 

[pcas1986]

…..

I know this sounds pedantic, and in some ways, I'm preaching to the choir, and I also know that to in order to stay in business, they have to keep coming up with new ways to reinvent a wheel and throw new features out faster than they can be fully tested, but it's going to get to a point where the developers are going to have to stop, look at the mess they created, and clean up what's been done.

And pigs will be flying business class when that happens.

In the meantime I will plan to keep my few WiKi pages up to date with several technologies changing almost daily.

 

[pware]

Once the basic program is fixed, adding new features on top will be much easier to add to the wiki rather than having to go back and constantly update stuff that shouldn't need constant updating.

Alas, from my experience in writing documentation for Trainz and other technologies, having the "basic program fixed" often makes no noticeable difference to the task. Usually the older "fixed" sections still have to be rewritten because new features have forced changes to the UI, methodologies, operations, etc. The closest to having the "basic program fixed" in Trainz would be Surveyor Classic which has had no or very few changes that I have noticed since the introduction of S2.0.

 

[JCitron]

Alas, from my experience in writing documentation for Trainz and other technologies, having the "basic program fixed" often makes no noticeable difference to the task. Usually the older "fixed" sections still have to be rewritten because new features have forced changes to the UI, methodologies, operations, etc. The closest to having the "basic program fixed" in Trainz would be Surveyor Classic which has had no or very few changes that I have noticed since the introduction of S2.0.

It's that ever-emulsifying mass that programs are made of that makes documenting them difficult. I agree Surveyor Classic is at that point where that has finally turned to semi-solid gel.

From my experience, it's been the opposite since the basics are already there in place and don't need to be revisited. Occasional updates to the original are not uncommon from my experience but the overall document is no longer in a constant state of flux.

 

[ek.skirl]

And pigs will be flying business class when that happens.

Oh, I saw some piggy people flying business class. Is this the beginning of this proclamed future?

 

[ek.skirl]

One nearby thing:
I tried to correct some errors (may be I wrote them by myself?) at https://online.ts2009.com/mediaWiki/index.php/HowTo/Search_for_objects_in_the_world (see discussion page there), but I'm no more able to do so.
Reads this thread some one of the admins from the wiki to set me able to correct it as mentioned there, or do it for me?

 

[pcas1986]

One nearby thing:
I tried to correct some errors (may be I wrote them by myself?) at https://online.ts2009.com/mediaWiki/index.php/HowTo/Search_for_objects_in_the_world (see discussion page there), but I'm no more able to do so.
Reads this thread some one of the admins from the wiki to set me able to correct it as mentioned there, or do it for me?

I don’t recommend correcting any pages where N3V programming staff have been the sole authors. We can’t possibly know more than they do.
That may be the page that was subsequently locked.
If you have additional information on the topic that may be useful to others it might be better to add a new page. Getting someone to independently validate your additional information is recommended.

 

[pware]

I tried to correct some errors (may be I wrote them by myself?) at https://online.ts2009.com/mediaWiki/index.php/HowTo/Search_for_objects_in_the_world (see discussion page there), but I'm no more able to do so.

I can confirm that the page has been locked. The "Edit" option has been removed.

 

[ek.skirl]

If you have additional information on the topic that may be useful to others it might be better to add a new page.

This isn't an additional knowledge, only a correction of error. So a new site seems o me be overdone. And I leaved a comment on this at the discussion page. So the stuff should and have to react.
So long for this. There may be nothing done by normal users.