[mainline] Help needed for Help sections

[Iris]

Hi there!

Currently, when Wesnoth is started for the first time, some Help sections are not populated with any topics at all, and there’s no visible explanation for this as far as the user is concerned. Right now, this is the case for the Units, Abilities and Weapon Specials sections.

The reason these sections are empty is that they are affected by the unit discovery mechanism (which you can opt out from in Advanced Preferences). Before the player encounters any units they will, of course, be completely empty. As players make their way through the game, they will stumble upon new units and new accompanying abilities and weapon specials to be added to the Help index. The top-level topics for these sections then include an ever-expanding list of entries accordingly, as you most likely know.

In order to reduce confusion amongst newcomers (see FR #13914 [Gna.org]), we want to include short blurbs in each section description explaining the deal to the users. Since ‘we’ in this case obviously means ‘I’, and I’m not particularly good at writing user-level documentation, I would like to ask for your help in this noble endeavor.

All you need to do is come to a consensus regarding what the descriptions of the three aforementioned sections should be, and I’ll make sure to land them in trunk in time.

So, go ahead and brainstorm away. But keep them short, concise, professional, and to the point. And most importantly, use well-formed, proper U.S. English in all cases.

[Daravel]

Units
This section will list all the units you discover as you explore the world of Wesnoth. When you meet a new mainline unit during a campaign or multiplayer scenario then it will be added to its races' subsection; you can then look up that unit at a later time. A unit’s page will provide a short description, its statistics, attacks and resistance, movement and defence values.

Abilities
This section will list all the unit abilities you discover as you explore the world of Wesnoth. When you encounter a new mainline ability during a campaign or multiplayer scenario then it will be added to this list; you can then look up that ability at a later time. Abilities are unique skills that are available to certain units and can provide benefits or define a role for that unit. An abilities page will provide a description of what that ability does and which mainline units have that ability.

Weapon Specials
This section will list all the special weapon types you discover as you explore the world of Wesnoth. When you encounter a new mainline weapon special during a campaign or multiplayer scenario then it will be added to this list; you can then look up that weapon special at a later time. A weapon special is an extra effect attached to a normal attack. A weapon specials page will provide a description of what that special does and which mainline units have that special.

I made a point of specifying 'mainline' because while UMC units do appear in the help pages while playing that specific camapign or era they dissapear when you are not. It may be worth putting a statement to that effect on there too "Custom or "user-made content" will appear in these sections while you are playing a campaign or scenario in which they are used but they are not saved to the help file permanently"

Is this what you were thinking of?

[Iris]

I made a point of specifying 'mainline' because while UMC units do appear in the help pages while playing that specific camapign or era they dissapear when you are not. It may be worth putting a statement to that effect on there too "Custom or "user-made content" will appear in these sections while you are playing a campaign or scenario in which they are used but they are not saved to the help file permanently"

It would be nice to clarify that point as well without raising too many new questions for the player.

As for the content itself, I’m not sure how I feel about the incessant repetition of the keywords, especially for the Abilities and Weapon Specials descriptions. Given how things work at the moment, the title of the current topic is displayed in larger bold face at the top, so there shouldn’t be a need to hammer it in like this.

I also forgot to mention that Abilities and Weapon Specials already have short descriptions that only need to be fleshed out further.

[TheCripple]

"Mainline" is pretty much jargon to new people, it sees heavy forum use but not much else. I'd recommend not using that term.

[artisticdude]

A derivative of Daravel's work:

Units
This section lists all the units you discover as you explore the world of Wesnoth. Whenever you encounter a new unit during a campaign or multiplayer scenario, that unit will be added to its race's subsection; you can then view it's page any time you wish. A unit’s page will provide a short description of the unit, its statistics, attacks, resistances, and movement and defense values.

Tried to pare down the use of keywords a bit, hopefully not at the expense of clarity (it seems fine to me, but...). I changed the tense of "will list" to "list", but that's based more a personal preference than anything else. I also removed all mention of the word "mainline", but I feel like some synonym of the word should still be used (perhaps "core" or "default"?).

I don't have a local copy of Wesnoth ATM, so I'll wait 'til later to mess around with the existing abilities and weapon specials descriptions.

[Daravel]

As for the content itself, I’m not sure how I feel about the incessant repetition of the keywords, especially for the Abilities and Weapon Specials descriptions. Given how things work at the moment, the title of the current topic is displayed in larger bold face at the top, so there shouldn’t be a need to hammer it in like this.

I also forgot to mention that Abilities and Weapon Specials already have short descriptions that only need to be fleshed out further.

I included a short description of abilities/weapon specials loosely based off what was in the help file already - The text proposed here should be able to wholly replace it all.

Adapted version of artistic's for unit:

Units
This section lists all the units you discover as you explore the world of Wesnoth. When you see a new unit during a campaign or multiplayer scenario it will be added to its race's subsection; you can then view its page any time you wish. A unit’s page will provide a short description of the it, its statistics, attacks, resistances, and movement and defense values.

- Whenever -> when (easier word for non-native speakers)
- encounter -> see (easier word again - and "see" can be used for abilties and weapon specials making the text more uniform)

Apart from that, it looks great to me. I was just conscious of making it easy to read for everyone

Abilities
This section will list all the unit abilities you discover as you explore the world of Wesnoth. When you see a new ability during a campaign or multiplayer scenario it will be added to this list; you can then view its page any time you wish. Abilities are unique skills that are available to certain units and provide benefits or define a role for that unit. Its page will provide a description of what it does and which units have it.

- Reduced usage of "ability" and made the format more similar to the units section

Weapon Special
This section will list all the special weapon types you discover as you explore the world of Wesnoth. When you see a new weapon special during a campaign or multiplayer scenario it will be added to this list; you can then view its page any time you wish. Weapon specials are extra effects attached to normal attacks. Its page will provide a description of what it does and which units have it.

-Same again. Hopefully clarity is not lost.

[Iris]

- Whenever -> when (easier word for non-native speakers)

Non-native speakers would hopefully find and use a translation if they cannot understand this word—which is very simple and common—or in-campaign prose, which usually consists of overly formal or archaic-sounding English.

I prefer ‘whenever’ here, personally, but:

- encounter -> see (easier word again - and "see" can be used for abilties and weapon specials making the text more uniform)

Given this, I guess we can stick to “when you see” instead.

Your last batch of descriptions look good enough for committing for me, except for one inconsistency:

(Units) This section lists all the units you discover as you explore the world of Wesnoth.
(Abilities) This section will list all the unit abilities you discover as you explore the world of Wesnoth.
(Weapon Specials) This section will list all the special weapon types you discover as you explore the world of Wesnoth.

It seems to me like the second form (“This section will list all the X you discover [...]”) fits the two most important border situations better; this is, both when the section is not populated with topics (i.e. fresh game configuration), and when the section is populated with as many topics as it can ever be (i.e. all mainline campaign units encountered).

I am, however, bothered more by the expression “the world of Wesnoth” in both cases. This could lead to ambiguity where the player might understand Wesnoth to be not only the larger human kingdom in the Great Continent, but also the name of the world itself, which is stated elsewhere to be Irdya. Thus, I’d suggest the following form instead, using italics as in the Overview page to refer to the game’s title rather than an element that’s part of the setting:

This section will list all the X you discover while exploring the world of the Battle for Wesnoth.

[Daravel]

- Whenever -> when (easier word for non-native speakers)

Non-native speakers would hopefully find and use a translation if they cannot understand this word—which is very simple and common—or in-campaign prose, which usually consists of overly formal or archaic-sounding English.

I prefer ‘whenever’ here, personally, but:

- encounter -> see (easier word again - and "see" can be used for abilties and weapon specials making the text more uniform)

Given this, I guess we can stick to “when you see” instead.

Agreed. I'm always overly conscious of using complex English words (which, as you point out, whenever isn't one!). It's easy for me to sit here and spew out all manner of posh sounding words.

Your last batch of descriptions look good enough for committing for me, except for one inconsistency:
*snip*
It seems to me like the second form (“This section will list all the X you discover [...]”) fits the two most important border situations better; this is, both when the section is not populated with topics (i.e. fresh game configuration), and when the section is populated with as many topics as it can ever be (i.e. all mainline campaign units encountered).

Agreed.

I am, however, bothered more by the expression “the world of Wesnoth” in both cases. This could lead to ambiguity where the player might understand Wesnoth to be not only the larger human kingdom in the Great Continent, but also the name of the world itself, which is stated elsewhere to be Irdya. Thus, I’d suggest the following form instead, using italics as in the Overview page to refer to the game’s title rather than an element that’s part of the setting:

This section will list all the X you discover while exploring the world of the Battle for Wesnoth.

I chose "explore the world of Wesnoth" because it add an (albeit tiny) element of roleplay, as in, "brave adventurer, on your travels you will encounter many wonderful creatures". However, I do agree that the Battle for Wesnoth is beter; but for this case I'd suggest changing "while exploring the world of the battle for Wesnoth" to "while playing Battle for Wesnoth". I think it flows better?

[alluton]

I chose "explore the world of Wesnoth" because it add an (albeit tiny) element of roleplay, as in, "brave adventurer, on your travels you will encounter many wonderful creatures". However, I do agree that the Battle for Wesnoth is beter; but for this case I'd suggest changing "while exploring the world of the battle for Wesnoth" to "while playing Battle for Wesnoth". I think it flows better?

explore the world of Wesnoth does sound good actually. Giving much better impression than: when playing battle for Wesnoth.

[Iris]

When the time came to commit the changes, I wasn’t too happy with what I took from here, so I amended it a bit; I ended up mixing the pre-existing descriptions with the suggestions from this topic and my own ideas.

The prose I actually committed to trunk ([rev]54063[/rev]) the other day follows:

Units
This section will list all the units you discover as you explore the world of Wesnoth. When you see a new unit during a campaign or multiplayer scenario it will be added to its race’s subsection; you can then view its page any time you wish. A unit’s page will provide a general description, its statistics, attacks, resistances, and movement and defense values.

Abilities
Certain units have abilities that either directly affect other units, or have an impact on how the unit interacts with other units. These abilities will be listed under this section as you encounter them. Each page will provide a description of what the ability does and which units have it.

Weapon Specials
Some weapons have special features that increase the effectiveness of attacking with them. When you see a new weapon special during a campaign or multiplayer scenario it will be added to this list; you can then view its page any time you wish. Each page will provide a description of what the weapon special does and which units have it.

[Daravel]

Only two tiny comments, so feel free to ignore them.

I don't think the comma is needed here: "Certain units have abilities that either directly affect other units, or have an impact on how the unit interacts with other units."

"Each page will provide a description of what the ability does and which units have it"
For both abilities and weapon specials would it be a good idea to say "and which units (that you have discovered) have it?"

But it looks great to me.

[Iris]

For both abilities and weapon specials would it be a good idea to say "and which units (that you have discovered) have it?"

How about “[...] and which (currently known) units have it.”?

[Daravel]

Bah! I can feel myself falling into my usual trap. "It's just one word" I tell myself.
"known" doesn't sound right to me, "currently discovered" perhaps?

Then again, I always get hung up on singular words; it's not that important

[Swiss_Army_Cheese]

Singular words are that important.
I personally, lean on the "currently discovered" side of the fence. I reckon it gives feeling that the player still has much more to find out, and that if he looks hard enough, the encyclopaedia may be more and more filled in a rewarding effort of exploration. On the other hand, the use of "currently known" gives a feeling of "Eh, maybe if I look in it tomorrow there will be something interesting in it".

[Iris]

“Currently discovered” it is, then. Committed ([rev]54137[/rev]).