On Sat, Mar 6, 2021 at 6:55 AM MG <mg...@arscreat.com> wrote: > @we'd want the full info somewhere: Agree. > But since the annotation section headers already have the fully qualified > name and the user gets taken there when he clicks the annotation (short) > name on the sidebar, so I feel we are good here :- >
Potentially, but the sidebar is generated automatically from the section header names last time I looked. I am sure numerous tweaks might be possible. > Cheers, > mg > > On 05/03/2021 20:45, Paul King wrote: > > I agree some improvement in presentation would be great. The main thing > for me is to remember that most of the HTML doco is generated (asciidoc or > templating). So as long as we modify things from the sources, that should > re-generate better. Also, we now also do a PDF version of the > documentation. It also needs improving but we certainly wouldn't want it to > get worse when trying to fix the HTML. > > Wrt displaying fully qualified vs simple name, we can possibly change but > we'd want the full info somewhere. I.e. the index entry could be shortened > but when clicking through the actually heading of the subsection would > contain the package name. Other alternatives might be to display the > fully-qualified name when you hover over it or group headings under package > name sections - again we'd need the asciidoc/templating changed unless we > post-processed the HTML somehow (and PDF if needed?). > > Cheers, Paul. > > > On Sat, Mar 6, 2021 at 1:55 AM MG <mg...@arscreat.com> wrote: > >> Hi Leo, >> >> thanks for your input. My take on this is: I am not against the current >> tables, but they need some improvement (padding and maybe some lines (if it >> is a table, why not present it as such ?)). If that improvement is not >> coming, I would be for taking up your offer to rework them in a >> glossary-like style as you suggest (from the top of my hat it feels like >> you suggestion could also help with mobile rendering of the Groovy >> documentation, since it by nature is more vertical than a tabular approach). >> >> What do others think ? >> >> Cheers, >> mg >> >> >> On 03/03/2021 22:01, Leo Gertsenshteyn wrote: >> >> 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 >>> >>> >>> >>> >> >
