I think my little closing rant might have dropped the tone of this thread. Sorry for that. It was late and I just had a meatspace argument with another open source fan about a similar topic. Not that that excuses me.
As for the wiki/documentation, I'm actually not sure what the update's content should be. With square grid maps, it's broadly accepted across many games that diamond shaped tiles means "isometric" and square tiles means "non-isometric". There isn't an accepted orientation for hexagonal tiles, though.
So I don't know which part of the wiki is incorrect or incomplete.
When is_hex is specified (see is_hex, below), this value gives the length of the extra side of the hexagon. This extra side will be on the top/bottom of the tile if is_isometric (below) is given, or on the left/right of the tile otherwise.
(from the "hex_side" entry) This defines the orientation of the hexagons, and the boolean value for is_isometric contradicts this. But it's not clear whether the boolean is reversed or the definitions are wrong.
What does an isometric hex tile look like? Is the top a vertex or edge? It's not at all obvious, though I do think vertex-at-top makes more sense for perspective views (as in civ5; and since iso-square is also vertex-at-top) while edge-at-top is better (or maybe just not worse) for non-iso (worked nicely for Civil War General). Personally, because of this ambiguity, I'd rather see the hex tiles delineated differently (say, using "___-at-top" rather than "is_isometric"), so they're defined by pathing rules, not by assumptions about the graphics. Then just let artists pick which orientation they'd like to use, and choose whether to use foreshortening or not:
As for unit_height and unit_width, can't experimental features that at least sort of work still be documented? Why not just document the feature, but slap a "this is experimental" disclaimer on it? Then it's all out there.
The effect of unit_height and _width is difficult for me to figure out. I've tried a number of sizes from 0 to 256, and all that seems to happen is that the graphics get a little glitchy. The units stop blinking while selected, and are partly obscured by the terrain. There is no visible effect, however, on the things I've been trying to fix.
Thanks to all for your input so far.