Topic: Content and looks of the new "cheap in-game help"

Hello everybody!
SirVer has openend up a LUA based opportunity to add simple help text to each of the house windows, and I am volunteering to design and type the text for all of them.
I am opening up this thread so that everybody can utter his views on the content and layout of these text that are in the making.
I have choosen this forum, because it is my firm believe that an automatic translation of such help texts will not be adequate for this kind of writing; so I expect there is a good bit of work for the native speakers of those languages that WL is already supporting.
Referencing data from the game and maybe even some graphics will be done calling Lua functions, whereever appropriate, to keep the help system easy to maintain.
( as soon as I get some clues about how to do it )
Opening up a new forum for help texts might be better, but for now this place is the best I could think of.

I am myself a native German speaker, but given the importance of English help text, I am willing to similtainously write those, unless of course some native English speaker steps up to do the job within a reasonable time frame.

I will post of few topics here as they emerge and hope for some feedback from our regulars.
So - come on, express your thoughts!

Being no programmer, I apologize for all my suggestions that imply undue workload and for other misjudgements due to lack of expertise or relevant skills.
I am on Win32, have no means to compile, and rely on prefabricated distributions (Thanks to Tino).

Top

Quote

Astuur, I have designed the ingame help windwo with some flexibility in mind. If you take a look at the help.lua for lumberjacks you'll realize that it returns a lua table which is basically a colection of key->value pairs. Currently, only text = "is used":

return { text = _"Hello World" }

but nothing stops us from defining a syntax in a way that works like that

return {
  tabs = {
     {
        text = _"Text of the first tab",
        tab_picture = "pics/general_help.png", -- Graphic for the tab button
     },
     {
        text = _"Text of the second tab",
        tab_picture = "pics/blua_help.png",
     },
  }

}

I can deliver this if you really want that :). Note that there will be a lot of code duplication in the various buildings that have the same tabs (for example the pics reference), so the construction of the 'tabs' array could be moved into a lua function that could be moved into a common file.

function make_tabs_array(t1, t2) 
  return { {
        text = t1,
        tab_picture = "pics/general_help.png", -- Graphic for the tab button
     },
     {
        text = t2,
        tab_picture = "pics/blua_help.png",
     }
  } }
end

return {
  tabs = make_tabs_array(_"Text of first tab", _"text of second tab")

}

Also note the "_" in front of strings. This means that this string will get translated; every text will appear in the launchpad translations page for the tribe that defines the help and if it is translated and merged back the localized string will be used. This should work already.

I realize that this is quite a paradigm shift from the conf files we have for other stuff, we're not really talking static text here but rather a programmatic approach to the help. I will help to bridge this gap as good as I can.

I have designed with flexibility in mind; however I suggest to just get started with what is available now and then refining (in various tabs for example) in the light of discussion.

Top

Quote

I like the General section, though I'd personally would love to see a short 'lore' like paragraph before diving into the details.

For the details however, I personally think that there is too little visual clues and to much running text. Whenever possible a short information should suffice. I suggest to show all information graphically and only ammend stuff via text.

For e: Finding information in this paragraph is rather tedious as you have to read through long sentences to find the information you search. I'd suggest a more visual clue; I worked on your example and redid the building section for the lumberjack (I stopped there, it is just to exemplify my point), see [1].

I also reworked this with some helper functions to also underline my point of simplifiying writing helps with lua from my former post. This is also just to convey the idea. See [2].

The result looks like this:

I realize that one feels quite handicapped with the current widelands rich text renderer, but for the moment it must do.

[1] https://gist.github.com/1360716
[2] https://gist.github.com/1360742

Top

Quote

Hi fuchur - thanks for th comment For me the range is shown automatically whenever I open a relevant production site window.
Is this different for you?
I can switch it off, but it will again be shown the next time I open that window. So I think, we may not need an extra mechnism for that. But I think my texts should at least mention that feature: in that sense I will modify the writing.

Being no programmer, I apologize for all my suggestions that imply undue workload and for other misjudgements due to lack of expertise or relevant skills.
I am on Win32, have no means to compile, and rely on prefabricated distributions (Thanks to Tino).

Top

Quote

Well Sirver - time for a little clarification of standpoints and preferences. I feel it is necessary, even though it's kind of lengthy (again, I know ).
First and foremost - I thank you for the help and assistance you are giving.
Your support is much appreciated here - and in fact, I wouldn't even start to think about so complex structures, it it wasn't for that.
On the other hand, please try to understand, that I don't want to become a programmer.
I share the fascination about what you can achieve with knowledge and some tools, but it's the outcome I like, not bothering with
indented line, keywords or any form of syntax. I can see practically all our regulars now shaking their heads, but that's okay.
Having said that, I concede that the modest use of functions that you are introducing to show some trunks or build help symbols certainly is helpful - and I may learn how to use them sooner or later.
So far, so good.
What I really like you (and others) to understand is related, but still different.
I am sure you have followed most of the discussions about new graphics, houses in that case, that I had with Chuck.
We both agreed that the genuine charm of especially a game like Settlers or Widelands lies, among other things, in the attention that
is given to tiny little details. "Giving some love" to the work is more than a figure of speech.
And look how Chuck has succeeded in doing exactly that!
Recycling - as in "using the same thing again at different places and for a different purpose" may be something that coders go for, but when it shows, like in prefabricated blocks in houses, it becomes detrimental for the feeling of "love" being invested.
This is obvious in graphics, but IMO it becomes just as obvious when a text block is re-used over and over again.
So far, there has been not much chance for falling into that pit textwise with WL, since there has not been a lot of text in the game itsself. (except for the campaignes, where there is no redundant information).
In any case I'd like to keep my safe distance; i.e. when in doubt, write things twice in different words rather than using text blocks.

I am writing all this because I sense your tendency to keep things terse and structured - the way a programmer would.
Me, I'm more of a language man. I believe in the power (and the beauty) of language and I tend to rather write more for clarity, than less accepting ambiguity or incompleteness.
In fact, 2 years ago, I had even played with the idea of writing a WL handbook in a narrative style, something that would immerse the reader into the WL world including the tribes' history.
I had to give that up of course, because the history is yet undecided in major parts, but it helps to show you where my preferences are.
So...

I realize that one feels quite handicapped with the current widelands rich text renderer, but for the moment it must do.

Not at all, Sirver! I can live with the fact that the font is vanilla, bold and italic seems not to be available, as long as I have some means to not let the reading become too awkward. That is fine.
The real problem, however, is not about what I would like to do - I accept that this should be primarily informative - it is one of audience: Especially for the english language we must take into account, that we may have players who cannot use their native tongue because it isn't supported. They will most likely resort to English, and their command of this language may be minimal.
They won't give a damn for "beauty" but want info that they can decipher. I have tried to keep the writing simple for exactly this reason.
And it is at this point, that the structured graphical display you made possible is most welcome and useful.
So, all in all; though I really want this to look "handmade" and avoid any "auto-generated" feeling, I acknowledge the need for a
concise quick information at a glance, even for linguistically challenged players.
What would you think about tabs for "not so quick" or "in-depth" descriptive help with predominantly text?
For me nothing speaks against doing both: a quick help for forgotten details, and, behind tabs, some longer texts for more details.
I am not so sure what information you would expect in the "lore section" of a lumberjack? Please clarify!
What's the current schedule for the next official version? You want this in there, don't you?

Being no programmer, I apologize for all my suggestions that imply undue workload and for other misjudgements due to lack of expertise or relevant skills.
I am on Win32, have no means to compile, and rely on prefabricated distributions (Thanks to Tino).

Top

Quote