JJ
commented
6 years ago I think that, as long as we came up with a good way, as in unobtrusive and informative, this could be a very interesting addition to Roles, and maybe classes as well. The information should be in the type graph already. It's only a matter of rendering it nicely. WRT to the chart, the main problem is that the elements of the chart themselves are clickable so making the void space among them also clickable might get a bit confusing from the UX point of view (but I don't know the first thing about UX, so that might be kosher). Changing the clickable text is doable, and if you don't mind, I'll create a separate issue for that.
Request for Enhancement:
To my semi-trained Perl Eye (I am an engineer), the documentation "seems" very well written as a refresher for very advanced and developer level users. For common users and beginners (the “RTFM” crowd), the documentation is a vast step backwards from Perl 5’s PerlDocs and is very difficult to use.
To help remedy the situation, I would like you to please consider the following:
To quote JJ, who said it better than I am going to: “"Repeat in every Role all the known classes that mix it in, or include in every class all known classes that subclass it"”
And to add to JJ's satement, when defining a “Role”, at the top of the article, please place all “Classes” that are members of that role. The idea is to start simple and then you guys can list all the advanced stuff afterwards.
For example (I am using “Set” notation and not Perl notation in the following):
"Real" is a "Role" that includes the following classes:
Real = {Rat, Rational { Rat, FatRat }, Instant, Duration, Int {FatRat, int, Signal, Autoicint, PromizeStatus, Bool, Automicint, Sinval, Order, Bool, InStr }, Num { NumStr } }
With the name of every member of set being a link to its document.
If instead, you wish to use a chart, like https://docs.perl6.org/images/type-graph-Real.svg, please use the full chart in the documents and not a tiny, blurry expando chart.
And if you really, really want an expano chart, change the expando button’s name from “Stand-alone image: vector” to “Expand Chart” or just “Expand”.
And if using a chart, make sure the cart is moved to the top of the article and not buried deep in developer level documentation. Start simple.
Please keep in mind that some of us do “Read The Freakin’ Manual” (RTFM). Please endeavour to make it readable for beginners as well as advanced users. Perl 5’s PerlDocs gives many wonderful examples.
Many thanks, -T