MG, thanks for bringing this up! I hope you don't mind my potentially hijacking your thread to briefly agree with one of your points and then expand on one of the others you brought up...
# Left-nav too narrow I think your idea of not using the fully qualified names makes a lot of sense. If someone really is looking at this documentation to see what is available, we'd want to make it as easy as possible for the eye to scan over the most distinctive part of each of these. (Namely, the "simple name".) # Sample code boxes too narrow This has bothered me as well and at some point I tried to wrestle with the groovy-site tooling to do some reformatting but I never got it to the point where it was ready to submit a PR. Let me briefly describe my idea and if I don't hear a chorus of "no, that's terrible, we would never merge that", I'll be happy to do the work. ### My core argument: tables are for figures, not documentation It certainly appeals to many of our technical minds to make this stuff a table, but it's really just not an effective choice for documenting anything that will contain more than a few words in any given cell. I submit the following examples of comparable documentation, which all use some approximation of a Glossary format <https://www.w3.org/MarkUp/1995-archive/Lists.html>: * https://docs.python.org/3/using/cmdline.html#miscellaneous-options * https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javac.html#options * https://projectlombok.org/features/all ### My proposal Let's aggressively convert tables into glossary-like layouts to make the documentation (1) easier to use, and (2) more professional-looking. I believe if we want to keep the language thriving these little "perception" things can make a big difference with regards to it encouraging adoption within mature organizations. ### Feedback? Thanks for reading this far! I'd love your thoughts, even especially if you think I'm wrong. I'd rather hear it now than after I spend a few hours reformatting our documentation. :) Cheers, Leo On Mon, Mar 1, 2021 at 12:38 AM MG <mg...@arscreat.com> wrote: > Hi list, > > I just saw that the formatting of the Groovy documentation in Google > Chrome 88.0.4324.190 (Official Build) (64-bit) (see attached screenshots) > and Firefox 86.0 (64-bit) has some problems (100% zoom level, 2560x1440 > full screen): > > 1. The left margin is too small for annotation names, which go > underneath the explanation column on the right, e.g. > @groovy.transform.InheritConstru (imho one of the most important Groovy > annotations - a shame if anyone would miss that ;-) ) > 2. There is no separation between table columns, e.g. for > @groovy.transform.builder.Builder strategies, making this very hard to > read. > 3. Conversely the sample code boxes for @groovy.transform.Sortable > right above that are very narrow (and are showing a useless horizontal > scroll bar), making the code samples unecessarily hard to read. > > > For the first point, not using fully qualified annotation names would > solve the problem while at the same time imho making the presentation less > cluttered. > > Cheers, > mg > > > >
