News:

Simutrans.com Portal
Our Simutrans site. You can find everything about Simutrans from here.

The help texts are too verbose/long

Started by Spike, January 27, 2012, 12:50:17 AM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

Spike

IMO the English help texts are too long. People don't like to read help texts, much less long help texts. The long texts are intimidating to new players.

Online/in-game help must be of easy language, as short as possible to still contain all needed information do do what the player was looking for.

If not possible to gather all information in one short text use the pyramid scheme: One short entrance text with the most frequently needed information with link to more detailed information if it wasn't enough.

Edit: why do I need to explain this at all?

sdog

Quote from: Hajo on January 27, 2012, 12:50:17 AM
Edit: why do I need to explain this at all?
Are there help texts ... ?
(long time players -- thus forum population -- have looked at the help texts sometimes years ago or never. Unless someone is actually looking for things that need improvement (as you do) it is easy to overlook.

Ters

The few times I intentionally open the help window, I usually have trouble finding the relevant section. Sometimes it might not even be there. But I guess bad documentation is unfortunately to be expected from a project without a dedicated documentation team. Then again, the documentation in Simutrans isn't much worse than the documentation for some expensive pieces of software I deal with at work.

sdog

i can't remember when i tried to use in-game help or documentation. i typially just searched online.

(i used the gnuplot internal help three years ago, with horrible results. also perl makefiles/documentation, both while being cut off from the net.)

Now, simutrans has rather low demand for computer hardware, if played in countries with less excellent connection (i'm thinking on brasil for example) it might be quite important though. As a consequence, perhaps this should be focused on areas where the demand is the highest, and on english as a lingua franca.

Spike

I've been learning from this book, first edition though. It's a good book IMO even if old, and it is quite affordable:

http://www.amazon.com/Designing-Writing-Online-Documentation-Hypermedia/dp/0471306355/ref=sr_1_1?ie=UTF8&qid=1327658538&sr=8-1

People are still mostly the same as 15 years ago, that's why I think the ideas from the book are still valid. Also this is another reason why I dislike the translator - everyone, regardless of skill level or training can enter texts there. Help texts should be done by people who have some experience in the field.

ActAirNeer

I have to agree, UI is somewhat  "UnInviting" :P but you should see the program I work with at my job.

Puns aside, I'm willing to help with the English/Spanish texts. I don't have any formal training but I have dealt with documentation (maintenance manuals) at work and have a written one for the program we're developing.

As for standards, that book you mention Hajo looks interesting. I have dealt a bit with the "Simplified Technical English" (STE-100), an international standard used in aerospace, which could also be a reference. In English you also have the added differences between British/American spelling and words used, it's the same with Spanish (though spelling is more consistent).

I've written manuals in plain HTML (XHTML) which can later be converted into a single CHM file, used on a website, converted to PDF, used on eBook readers... I'm not sure if the Wiki has these options or not. If you believe it might be worth the effort I am offering to get started on it.

Spike

I'm sure any help will be welcome. But I don't know who is currently coordinating the translations.

prissi

The help text must cover the option of the program. Sorry, if you complain that one does not know how to use control, the help files are the way to get this know.

Since main computer screen resolution getting larger and larger, this length is less of a problem. Also the text are not long, if you do not want to stutter out phrase, which will not help anybody. The main problem is anyway, that nonody pressed F1 but everybody wanted simutrans to behave like the BeOS, KDE, Gnome, Win98, Window7, MacOS GUI ...

For the help windows the translator has a very nice preview.

Spike

Quote from: prissi on January 27, 2012, 11:11:33 PM
The help text must cover the option of the program. Sorry, if you complain that one does not know how to use control, the help files are the way to get this know.

It's just a UI guideline, that available options should be visible. And I agree to a big extend with this guideline. The help text can remedy this problem to some extend, but think of the big difference in time between a directly visible option, and reading through a help text.

And since players do not see the options - how would a new player develop the idea to search for it in the help text? He has no idea it could be there at first. I do not think people read those texts systematically, but only when they have a problem. Not knowing that one is missing knowledge is no trigger to learn, one doesn't even know that one is missing the knowledge ... so one doesn't feel any impulse to remedy this not observed lack.


prissi

There is nothing missing, that is not directly accessible by the menu/tool. That was the main design guidance, that you can play simutrans with a single button mouse and without control or whatever keys. But you will not get some advanced features: But show me a decent program, were you can get all features, without a manual or any other written documentation.

Since nobody wrote a manual in more than one language, the help files are the documentation. The wike is even more difficult to use, as you need actively to search where you are now, compared to just press F1.

Fifty

This would likely require a lot of coding, but it would be really nice to have a tutorial mode and a specially designed basic map that you could launch from a button underneath the "New Game" in the splash screen that would walk users through some of the basics

I remember 2 difficulties when I started Simutrans, years ago:
1. You need to build a Depot to build trains
2. You need to press signals twice to get one way

Here are some basic popups that could come up:
1. Click on the coal mine and note that its coal can only be consumed by specific consumers, in this case a power station. Press CTRL-J , type in the coordinates of the powerplant, and hit enter to go to its location.
2. Click and drag to build a single-track railroad between the mine and the power plant, ensuring that you have a freight-enabled station within 1 tile of the powerplant and mine. Press the CTRL key to build straighter, non-intersecting tracks.
3. Place a dead-end piece of track and build a railroad depot.
4. Build a train, selecting a locomotive and some coal cars. Be careful that your locomotive has enough power to reach whatever speed you desire.
5. Create a new line, add stations of the mine and the powerplant, and set the train to wait for a 100% load at the mine.
6. Apply the train to the line and start it, ensuring that the length of your train in station tiles is less than or equal to the length of your stations.
7. Hmm... one train won't cut it. Build a passing siding near the middle of your track, and place a one way signal by clicking multiple times on the standard signal on the track. (Show picture of how a correct siding should look)
8. Now build a second train and apply it to the line of your first train
9. Not enough production! Electrify the coal mine by placing a transformer from the special construction menu on both the mine and the powerplant, and connect the two with a powerline. You can see how much of a production boost electrification or passenger service will bring by clicking on "Chart" in the factory window.
10. People need to get to work at the mine! Build a tramway from the town hall of a nearby city to the mine. In town, trams can stop at bus stops, so place a bus stop on your tram track near the town hall. At the mine, you'll need to build a passenger station; make sure to build it next to your coal loading station in order to connect the stations!
11. Build a depot. Hmm, no trams? You'll need to click and drag the electrification tool over your entire tram line. Make sure the tile your depot is on is electrified too!
12. Build a tram of appropriate length, create a new line between the town hall and the coal mine. Don't set the loading factor to 100% for passengers: consider 80%. Also set a wait time to prevent the tram from waiting too long.
13. People can only walk to your station from two tiles away: build some bus stops to cover more of the town. Then build a bus depot, create a new line that brings people from all of your bus stops to the central stop at the town hall, and assign it to a new bus. Because bus capacities are small, it is often not useful to have a % wait load.
14. Congratulations! You are now ready to be a transport executive! Check out your finances window to see if you are turning a profit: if not, you can turn on freeplay mode in the player dialog in the main menu to keep you out of bankruptcy while you learn the ropes. In the main menu, you can start your new game or adjust settings.

While a bit of a greedy request, I think this would help make the learning curve much less steep; the rest of the tricks people can read the manual or learn as they go. IMO this is the best way to solve this problem and attract new players.

I am also a native English speaker and would be happy to assist with translations, the help documentation, or the wiki If I get some time.
Why do we park on the driveway and drive on the parkway?

Fabio

Any chance to implement this kind of starter's scenario in Dwachs' new scenario engine?

prissi

Maybe. If you can code an AI by scripts, you can certainly code a tutorial. This is the longest idea and was already out before I started.