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.python.org/3/using/cmdline.html#miscellaneous-options>
*
https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javac.html#options
<https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javac.html#options>
* https://projectlombok.org/features/all
<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
<mailto: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
