User Manual

[brianbarber]

It would be really nice to have a user manual. This trial and error business is, well, trying. Even having tooltip like popups for different graphical objects would help, such as explanations for the meanings of the different flags planted by the geologist.

BB

[Raul Ferriz (raul.ferriz)]

As far I can know, there is an ingame help. Sure that should be completed, but it is a work in progress.

[Peter John Hartman (peterjohnhartman)]

I'd be against in-game help; in fact we should gut the current in-game help and direct people to the wiki or online version of the documentation. (We should also ship with a local copy.) Why? First, it is easier to have non-programmers add help to a wiki/website than to the code. Second, it is less burden on the programmer. Third, I don't really *like* the in-game menu-ing system and I found navigating the help that does exist pretty impossible. By contrast, flipping over to a firefox session is dead simple.

This suggestion is made in the name of re-allocation of resources. We can then focus on other stuff.

[SirVer (sirver)]

I am refering a lot to the wares enceclopedia that is already in the game. I would also use other look up materials, so I am still in favor of an online help. Your point with the allocation and focus of man power is very valid though.

[Hans Joachim Desserud (hjd)]

If no one is currently actively working on this, I think "In progress" is misleading.

Also, see bug 676955 for more info on the development of the in-game (might be relevant).

[SirVer (sirver)]

I agree. Setting to confirmed.

[Joachim Breitner (nomeata)]

Ideally, the documentation would be maintained in some form that
 * allows non-programmers to modify it
 * will be compiled into the game as the encyclopedia and other spots
 * will also be turned into a nice and complete HTML and PDF user manual.

Maybe docbook is an option; if you label the indivdiual sections you can extract programmatically at build time the various fragments that should show up in the game as well.

[SirVer (sirver)]

Setting to incomplete for bug sweeping.

[SirVer (sirver)]

sorry - did not meant to set it to incomplete. bug in the script :)

[Tinker (room101)]

Is anything happening with this?

WL really does need a user manual, new players coming from similar games may adapt quite well but still be confused by some aspects. Totally new players may get hopelessly lost and give up, they will often be lost as users for ever and bad news travels fast, their friends may not even bother to look.

User manuals is perhaps I way I could help give back to the project to thank the code monkeys who work so well, certainly better than any code I have tried to write .

[wl-zocker (wl-zocker)]

Every building has now a help window which explains what it does, what it needs and where its wares go to.
There is the ware encyclopedia which gives a short help text about all wares.
There is a tutorial which explains some basics. I work on this and try to expand it so more things are explained.

@#9: What things do you miss? Naming concrete issues makes helping you/fixing them easier.

[GunChleoc (gunchleoc)]

The next thing on the help front that we should do is to integrate the new building help with the wares encyclopedia, so it will be available without the need to buid a building first. This is definitely on our want to have list.

[Tinker (room101)]

I was thinking, as proposed earlier, of a separate document, a PDF or wiki manual that contained the help window details, perhaps in more depth, the same with wares.

A getting started guide covering installing and setup before moving into the tutorial. The tutorial scenario's stand well on their own once the player gets there, even with some missing they are a great help.

I was thinking the manual would then move onto advanced topics, why you might want to upgrade or not a building, how to ensure your troops train etc. possibly some examples of styles of play, the different win options and of course multiplayer.

Correct me if I am wrong, but the ingame help does require coders to update it, if the manual was a wiki then none programmers could update it with perhaps one person as overseer to ensure consistent style and new features, like seafaring would be simple to slot in. For a release a snapshot of the manual could be included in the install. A lot of the information is already on the wiki, the forum or here but currently it is all rather messy to find. Searching for help on seafaring yesterday I ended up on a discussion about healing soldiers.

[GunChleoc (gunchleoc)]

The advantage of the in-game help is that it can be generated automatically, so it will update whenever the stats for something change. Working on the building help this year, I already found some stuff that was outdated.

What non-coders could do is write text for general stuff, like how to use seafaring etc.

The way our in-game helptexts work now is that they are all coded in Lua. This means you can change them without having to recompile the game. People will need to understand how to handle bazaar though.

We should work towards having everything in one place rather than scattered between the game and different sections of the wiki. Part of the Wiki is actually generated from the game's configuration and code files. Maybe we can tap into that to mirror the help on the Wiki then.

[wl-zocker (wl-zocker)]

#11: Seeing the build help of a building without having built it is very sensible. I think there is currently no way to check what workers an upgraded building needs.

#12: The user einstein13 has created some in-depth thoughts, you can find it under http://student.agh.edu.pl/~rak/widelands/. The strategy part contains some interesting ideas.
This is only plain text, so everyone can write something like that (without programming skills). In our wiki, everyone can create a new page. I think that is the easiest way to create such a content. Later on, we can simply reference to it.

#13: Please have a look at bug 350465 and bug 1336863. The later one describes some problems and why the Wiki is not up-to-date anymore.

In general, I think we need the help at least in two places: In the game and at our wiki (to keep the page open and continue playing and to look something up without starting the game). I doubt it is necessary to ship the stuff via pdf - a simple link to our wiki should be enough.

Btw, do you know "Battle for Wesnoth"? It has an awesome in-game help (with links) and offers the same information on their website.

[Tinker (room101)]

Personally I detest in game help and prefer never to use it. Tutorial scenario's are my limit - if they are well written, in general WL ones are good.

The interesting einstein13 documents were something I had already come across, but they are indicative of the current mess of information, these should more integrated with the wiki. The wiki itself is a problem, if you click the wiki button you see a game manual listed with three headings Basic Game Help which is more of an outline of WL, Tribes which is out of date and Customising which seems be be of little use. Alternatively if you click on Game Manual from the Wiki dropdown you get to something that is a beginning of a user manual, though some links like the WannaHelp one just lead to a bunch of 404 errors.

I am familiar with Wesnoth, I have been working on the user manual for an offshoot game, Hale, but with only one dev. progress is slow. The Wesnoth user manual is more like we should have, but I am a nut for manuals, I have loads as ebooks that I read for pleasure.

Is it OK if I try to get some order into the Wiki user manual? I am working now on some better organisational charts for buildings and wares, I can merge the two current manuals into one and add some placeholder headings for new articles to be written, hopefully encouraging users to add the information, or I will add it myself later.

[GunChleoc (gunchleoc)]

Sure, any help in getting the information more organized and accessible to users will be welcome :D

Not that some wiki pages are already auto-generated from the code, e.g. this one: https://wl.widelands.org/encyclopedia/barbarians/wares/

So, if you're logged in and there's a page you can't edit, that's a sign that it's auto-generated.

[wl-zocker (wl-zocker)]

To be honest, I rarely use the wiki to look something up, simply because things are hard to find. So when someone finally gets a structure into it, I would contribute to it.

The 404 errors might come from the website redesign we did some time ago - I did not see them before. However, WannaHelp links me to https://wl.widelands.org/wiki/WannaHelp/, which exists, but is outdated.

#16: Auto-generation is basically a good thing, but it should work properly. The list you linked is a good example: All renamed wares (e.g. axe -> ax) appear twice, where only the old name links correctly. It is basically the same problem as mentioned in bug 1336863.
It would also be nice if things could be added to such auto-generated sites. I think of in-depth description that are too long for the in-game help or that spoil gameplay.

[SirVer (sirver)]

I think shipping a pdf document is not really good. I agree that we finally need an online help (blocked on merging of the font_handler refactoring) and we should put some work porting it onto the website (so that we have the same information twice, once in-game and once online).

I disagree that we should have plaintext documentation on the Wiki. We would need to keep two documentations up to date which is horrible and not something I want to do. That does not mean that nobody can come up with the relevant information right now that we can put into the online help, however whatever is going to be written now should be written with the idea that it will be converted to the ingame help soon.

The ingame help will be a tree view¹ with links. All current help buttons will open this help window with the correct page opened. It can contain strategies, tutorial text and will contain the reference.

¹ http://en.wikipedia.org/wiki/Tree_view

[GunChleoc (gunchleoc)]

Migrated to https://github.com/widelands/widelands/issues/310