Documentation question - alphabetize lists of subcomponents?

I’m going through e.g. GamePiece.htm, and in addition to only listing about 80% of the traits it list them in a haphazard order.

Starts out listing them “in the order they appear in the Piece Definer” and then after a while it gets kind of random.

So…
(a) Alphabetize?
(b) In-the-order-they-appear-in-the-Piece-Definer?
(c) Hey! Let’s alphabetize them in the Piece Definer!

Brian

(d) Oh another option is to list them in one order, but have a differently-ordered “table-of-contents” at the top of the list.
(e) And then there’s the option of having the TOC list them in the same order :slight_smile:

c) then a).

Don’t touch it unless you are willing to do it right is my code cleanup mantra (and also why I’m not willing to going there yet). That way the surface ugliness is a constant reminder of the trainwreck underneath. If you kinda fix it, I’ll look fine to the next developer who comes along until he pokes around and goes “holy crap, WTF!”

I’m for c) also, and a dynamic version of it: let the dumb computer sort them alphabetically.

Will be a good exercise for practicing the Stream API too.

So far I made an alphabetized table of contents up at the top of the HTML.

Alphabetizing the Piece Definer’s trait list would bring some odd things to the top (Area of Effect!) but on the other hand it would mean Global Key Command and Global Hotkey weren’t miles away from each other.

One other thing it would mean… Trigger Action would be the very last entry!

My present PR is a “no code” PR at least for now, so any code stuff like this, if we decide to go for it, will be another PR.

Thus spake Cattlesquat:

So far I made an alphabetized table of contents up at the top of the
HTML.

Alphabetizing the Piece Definer’s trait list would bring some odd things
to the top (Area of Effect!) but on the other hand it would mean Global
Key Command and Global Hotkey weren’t miles away from each other.

One other thing it would mean… Trigger Action would be the very last
entry!

So…

It’s useful to have an alphabetical list.

It’s also useful to have a list grouped by some notion of importance.


J.

True true. I’m not sure the current “Piece Definer” order captures that, exactly, but a straight-out alphabetical list (in the Piece Definer) coooould have disadvantages too.

I’ll keep thinking about it while I’m doing the no-code part anyway, and I’ll think about possible proposals for re-ordering ('cause there are some definite stupids in there right now). Others might think of things too.

Brian

Thus spake Cattlesquat:

“uckelman” wrote:

It’s also useful to have a list grouped by some notion of importance.

True true. I’m not sure the current “Piece Definer” order captures that,
exactly, but a straight-out alphabetical list (in the Piece Definer)
coooould have disadvantages too.

If you’re talking about the order in the trait dialog box or some of
the context menus, I’m not sure there’s any real sense to it at all. You
could do about as well by shuffling the items before each time they’re
displayed. :slight_smile:


J.

Lol I could also do worse though :slight_smile: But I’ll come up with something that will be consistently better, and then we can argue about “how better” :slight_smile: