Create account / Log in

Documentation question - alphabetize lists of subcomponents?

Discussion area for the development team.

Moderators: uckelman, Tim M

Documentation question - alphabetize lists of subcomponents?

Postby Cattlesquat » July 31st, 2020, 4:58 pm

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
User avatar
Cattlesquat
 
Posts: 890
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: Documentation question - alphabetize lists of subcompone

Postby Cattlesquat » July 31st, 2020, 5:29 pm

(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 :)
User avatar
Cattlesquat
 
Posts: 890
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: Documentation question - alphabetize lists of subcompone

Postby m3tan » July 31st, 2020, 6:07 pm

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!"
User avatar
m3tan
 
Posts: 189
Joined: August 12th, 2018, 11:49 pm

Re: Documentation question - alphabetize lists of subcompone

Postby Flint1b » July 31st, 2020, 6:34 pm

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.
User avatar
Flint1b
 
Posts: 461
Joined: May 19th, 2020, 12:27 am
Location: Colonia Agrippina

Re: Documentation question - alphabetize lists of subcompone

Postby Cattlesquat » July 31st, 2020, 7:23 pm

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.
User avatar
Cattlesquat
 
Posts: 890
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: Documentation question - alphabetize lists of subcompone

Postby uckelman » July 31st, 2020, 8:03 pm

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.
User avatar
uckelman
Site Admin
 
Posts: 8847
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: Documentation question - alphabetize lists of subcompone

Postby Cattlesquat » July 31st, 2020, 9:37 pm

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.

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
User avatar
Cattlesquat
 
Posts: 890
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: Documentation question - alphabetize lists of subcompone

Postby uckelman » July 31st, 2020, 9:57 pm

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. :)

--
J.
User avatar
uckelman
Site Admin
 
Posts: 8847
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: Documentation question - alphabetize lists of subcompone

Postby Cattlesquat » August 1st, 2020, 12:00 am

Lol I could also do worse though :-) But I'll come up with something that will be consistently better, and then we can argue about "how better" :-)
User avatar
Cattlesquat
 
Posts: 890
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA


Return to Developers

Who is online

Users browsing this forum: No registered users and 2 guests