You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@groovy.apache.org by MG <mg...@arscreat.com> on 2021/03/01 08:38:16 UTC
Groovy Documentation Formatting
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
Re: Groovy Documentation Formatting
Posted by MG <mg...@arscreat.com>.
On 06/03/2021 04:06, Paul King wrote:
> On Sat, Mar 6, 2021 at 6:55 AM MG <mgbiz@arscreat.com
> <ma...@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 meant design- not implementation-wise :-)
> I am sure numerous tweaks might be possible.
Do you mean design- or implementation-wise ?
Cheers,
mg
Re: Groovy Documentation Formatting
Posted by Paul King <pa...@asert.com.au>.
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
>>>
>>>
>>>
>>>
>>
>
Re: Groovy Documentation Formatting
Posted by MG <mg...@arscreat.com>.
@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 <mgbiz@arscreat.com
> <ma...@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 <mgbiz@arscreat.com
>> <ma...@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
>>
>>
>>
>
Re: Groovy Documentation Formatting
Posted by Paul King <pa...@asert.com.au>.
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
>>
>>
>>
>>
>
Re: Groovy Documentation Formatting
Posted by MG <mg...@arscreat.com>.
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 <mgbiz@arscreat.com
> <ma...@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
>
>
>
Re: Groovy Documentation Formatting
Posted by Leo Gertsenshteyn <le...@gmail.com>.
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
>
>
>
>