Style guide for item descriptions
Posted: Tue Aug 02, 2016 10:25Currently, item descriptions are a bit chaotic.
There is no real style guide which
This leads to item descriptions like:
- “Stone”
- “Jungle Sapling”
but also
- “Iron bar”
- “dry sapric turf”
- “Screwdriver (left-click to (…))” (parenthesis as part of description)
My point is that all these descriptions may follow some rules, but not the same one, otherwise this does not explain the different capitalization.
My goal is to establish some sort of style guide and then write it down in lua_api.txt.
The only question which remains is: Which style to adopt?
First thing is capitalization:
Minetest Game seems to like to capitalize every fucking word which I find very irritiating. Tooltips are not captions or titles. Also, I don't consider item descriptions to be proper names. There is not a a single thing with the name “Stone” in the world.
The problem with using capitalization is also it is against English grammar if you try to paste an item description into text:
We have to keep in mind that tooltips are not the only place where item descriptions may be displayed.
The second thing are parenthesis / long explanations.
There are a few items where long explanations are inserted into parenthesis. I think this is wrong as this usually just makes the tooltip far too long. Also, it prevents from item descriptions being pasted into text as this looks awkward to always have the full explanation after every time you mention the item.
An extreme example of this abuse can be seen in Regnum 1.6.0.
So my proposal is here to flat-out out-rule all “explainy” descriptions. Parenthesis almost certainly would violate that.
This is more like a hack. The real solution would be that Minetest extends tooltips in a way that they convey more useful information, not just the description. But this is a different issue.
The scope of descriptions should be simply telling as much information in order to identify an item.
SUMMARY:
My proposed style guide for descriptions:
- Don't treat descriptions as proper names (i.e. not capitalizing everything)
- Write the description in such a way that it makes it easy to distinguish from other items
- Write the description in such a way that it can be used without issues in many places (not just tooltips)
- If possible, try to avoid naming collisions
- Keep long explanations out of the description (they could be written elsewhere)
- Writing all this into lua_api.txt
I am open to discuss particular style guide suggestions. My main concern is that we have a style guide in the first place to avoid description chaos.
There is no real style guide which
This leads to item descriptions like:
- “Stone”
- “Jungle Sapling”
but also
- “Iron bar”
- “dry sapric turf”
- “Screwdriver (left-click to (…))” (parenthesis as part of description)
My point is that all these descriptions may follow some rules, but not the same one, otherwise this does not explain the different capitalization.
My goal is to establish some sort of style guide and then write it down in lua_api.txt.
The only question which remains is: Which style to adopt?
First thing is capitalization:
Minetest Game seems to like to capitalize every fucking word which I find very irritiating. Tooltips are not captions or titles. Also, I don't consider item descriptions to be proper names. There is not a a single thing with the name “Stone” in the world.
The problem with using capitalization is also it is against English grammar if you try to paste an item description into text:
Collect a Stone to complete this task
We have to keep in mind that tooltips are not the only place where item descriptions may be displayed.
The second thing are parenthesis / long explanations.
There are a few items where long explanations are inserted into parenthesis. I think this is wrong as this usually just makes the tooltip far too long. Also, it prevents from item descriptions being pasted into text as this looks awkward to always have the full explanation after every time you mention the item.
An extreme example of this abuse can be seen in Regnum 1.6.0.
So my proposal is here to flat-out out-rule all “explainy” descriptions. Parenthesis almost certainly would violate that.
This is more like a hack. The real solution would be that Minetest extends tooltips in a way that they convey more useful information, not just the description. But this is a different issue.
The scope of descriptions should be simply telling as much information in order to identify an item.
SUMMARY:
My proposed style guide for descriptions:
- Don't treat descriptions as proper names (i.e. not capitalizing everything)
- Write the description in such a way that it makes it easy to distinguish from other items
- Write the description in such a way that it can be used without issues in many places (not just tooltips)
- If possible, try to avoid naming collisions
- Keep long explanations out of the description (they could be written elsewhere)
- Writing all this into lua_api.txt
I am open to discuss particular style guide suggestions. My main concern is that we have a style guide in the first place to avoid description chaos.