groovy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Gertsenshteyn <leo...@gmail.com>
Subject Re: Groovy Documentation Formatting
Date Wed, 03 Mar 2021 21:01:43 GMT
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 <mgbiz@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
>
>
>
>

Mime
View raw message