Good Old Days - DOCUMENTATION

Now this is really good Docs:

https://www.trainzportal.com/files/TANE/trainz_a_era_manual_digital_en_150513.pdf

It might even encourage me to drive trains>>>>

Nice ! I've never seen this. I suppose after using TRAINZ for 20 years I should probably learn how to use it.

As an experienced author of textbooks, 9 of them over the years, I can attest that productions like that:-

1. are not simple, easy or cheap to create
2. take a long time. 12 months was about the fastest I ever achieved and in that case I was one of several authors (but was also the overall editor). As I sometimes discovered, editing the work of others can be as time consuming as writing their work all over again.
3. once written are not easy to change. This applies to PDF as well as web and paper based - and I have experience in writing docs in all those formats

With technical documentation (such as a software manual) one of the major issues is keeping it up to date. Each time a new version, service pack, even a hot fix, is released changes have to be made to the manual.

One way around that issue is to only start writing the manual after all the changes have been made and the "final product" (does that actually exist anymore?) is released. It would be like releasing the manual for T:ANE after its support end date had been reached. The time delay would be unacceptable to most users.

Another often proposed solution is to start the manual writing at the same time the project is started so both can be released together. But, as any developer will tell you, the final product can be totally different from its starting plans or first few prototypes. Last minute (just before the release deadline) changes can cause havoc for the writers. So there will be a lot of wasted time and effort on the part of the documentation writers.

While we are on this nostalgia trip - remember the good old days when software came on floppy disks with volumes of printed manuals? My first copy of MS Word (I forget which version) came on multiple 3.5inch floppy disks (remember them?) and a box of manuals weighing several kilograms. That alone would explain the high cost, even back then, of the software.

I just had a look at my main commercial (purchased) software applications. Not one of them has a manual, PDF or web based, that comes anywhere near the standard or detail shown in that original Trainz manual. I take my hat off to the writers of that manual but we will never see the likes of that again (not unless the users are prepared to pay much more to cover the time and effort that went into its production).

My thoughts.

Documentation, whether online, in a downloadable document, or in print is only as good as its content. Quantity also doesn't mean quality either whether the manual is in print or a downloadable document. I use Avid's Sibelius software for music notation and that comes with a user-manual that's well over 1,000 pages. It's no longer in a printed format and is a searchable PDF. There's nothing wrong that since it makes things easier to look up...

Note the ...!

The information could be distilled down to a 20-page user guide without the fluff! I swear, the tech writers were looking to keep a contract, or they were high school students required to write a certain number of pages for their term papers. When I first got the software, I needed to add in my digital piano software so I could connect that as an instrument. The process distilled down to adding the .VST file to the VSTPlugins folder. Finding out how to do that, was absolutely infuriating because there's a chapter dedicated to setting up the virtual instruments, such as Piantoteq which I was adding to the software. The chapter must be at least 70 pages and the first 69 pages of it were fluff about the history of virtual instruments, and how wonderful they are. While this information is cool, it wasn't necessary and only got in the way.

Sadly, this is also true for Wikipedia and its spin-offs. There's a lot of good information there but it too can be hidden in the useless fluff, or in some cases totally worthless because it says absolutely nothing at all.

.
https://cdetrainz.com/images/trainz/Tutorials/Trainz%20Keyboard%20Shortcuts.pdf
.

Wow! Thanks! That is really going to be handy!

Still have the printed manual for Trainz Railroad Simulator 2006 that came with the DVD. There might be a few things that are still valid in it. I had 2004 but cannot remember if a printed manual came with the floppy disks.

Rob

MountE said:

Still have the printed manual for Trainz Railroad Simulator 2006 that came with the DVD. There might be a few things that are still valid in it. I had 2004 but cannot remember if a printed manual came with the floppy disks.

Rob

Click to expand...

The TRS2004 manual came as a book. The manual includes the valuable CCG which has really valuable information on such things as the important kind tag and category tag. The TRS2006 manual was pretty much the same as the TRS2004 one with more information on CCP and the all-new Content Manager Plus.

JCitron said:

The information could be distilled down to a 20-page user guide without the fluff!

Click to expand...

That "distillation" is the function of the person employed as the project editor. In your example either there was no editing or the individual authors "self edited" (usually a recipe for disaster).

Christopher824 said:

.
https://cdetrainz.com/images/trainz/Tutorials/Trainz Keyboard Shortcuts.pdf
.

Click to expand...

Thank you ! I just saved this PDF to my desktop for quick reference. Very convenient.

JCitron said:

I use Avid's Sibelius software for music notation and that comes with a user-manual that's well over 1,000 pages. It's no longer in a printed format and is a searchable PDF.

Click to expand...

I use Band in a Box 2022 for making backing tracks to play along with. That's about my speed for music making software.

OK......back to our regularly scheduled programing.

I remember translating in Italian the CCG 2006... It was just a translation work but takes ages

pware said:

That "distillation" is the function of the person employed as the project editor. In your example either there was no editing or the individual authors "self edited" (usually a recipe for disaster).

Click to expand...

This guide was most likely written and edited by a single person many years ago. Sibelius was purchased by Avid, a company that makes and sells video and audio editing equipment and software for the film and TV industry, that has only recently gotten into the consumer market. Like most things purchased by big companies very little has changed with the software and documentation other than the name on the packaging including bug fixes. They do add in other features which are available for "free" via a $150 per annum maintenance fee.

On-line documentation is all well and good if you know what you are looking for and it's accompanied by a comprehensive index the later of which Trainz documentation unfortunately sadly lacks. The various aspects of Trainz together with there functionality are generally well document, at times in considerable detail if only you can find it, thankfully with help from the Trainz community you eventually can but should that really be necessary. Unfortunately what is difficult to do while using a web-browser is to actually browse, flicking through those non-environmental friendly pages of a paper manual you are far more likely to discover and learn those hidden gems than the frustration of wading through 1,001 results of a web search. Peter

Not to mention that any manual should be accessible to those of varying abilities.