@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 :-)
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
<mailto: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.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
