Hello David,
Thanks for trying to make TomEE site more readable and accessible!
I would like to suggest a few more enhancements to make this site as
useful and easy to use as it deserves:
1. This site must have navigation links, or better : breadcrumbs
link, in all its pages.
Let me take an example: when I click on the link you gave as an
example: http://tomee.apache.org/tomee-7.1/examples/application-composer.html,
I arrive on a page which is missing the "context" : I should see that
I am in a documentation page for TomEE version 7.1, subsection
Examples, and I should be allowed to navigate from this page to "The
root of all TomEE docs / The root of all TomEE 71 docs / The root of
all Examples of TomEE 7.1 docs".
Alternative would be to show a TOC (Table Of Contents) next to
all pages, but I personally find TOCs takes to much reading space,
whereas breadcrumbs, if well designed (don't use too long identified
for each "nesting") only take a short space, usual at the top of the
displayed page (but under other navigation elements, like the Search
bar, see #3 below).
2. It would be nice to have (not mandatory) a way to switch from
version 7.1 of this page to 7.0 and 8.0.
3. A missing feature is a Search bar in the top of all pages,
allowing to search documentation / examples on TomEE site.
4. Would it be possible to add a "day / night switch button" ? (see
the Sun/Moon icon at the top right hand side of this site:
https://docs.influxdata.com/telegraf/v1.9/data_formats/template-patterns/),
I love this one, but it's a matter of taste here :)
5. (hard) Access to the site from mobiles sucks, requires zooming.
Ideally the styles should implement responsive web design to nicely
fit pages in small displays.
Disclaimer: I am not a web designer, but I've been participating to
couple of design reviews...
Kind regards,
Alexandre
Le dim. 2 déc. 2018 à 02:41, David Blevins <[email protected]> a écrit :
>
> Alright folks!
>
> Updated site published and with a refreshed CSS that is more readable.
>
> - http://tomee.apache.org/tomee-7.1/examples/application-composer.html
> - http://tomee.apache.org/tomee-8.0/docs/configuring-javamail.html
>
> I'm attempting to get this to a point where we can crowd source some
> non-automatable tasks. What I'm imaging we can all do in a divide and
> conquer fashion:
>
> - Categorize each document for an intelligent looking index
> - Review each document for formatting issues
> - Convert markdown documents to asciidoc
> - Fix inconsistent h1, h2, h3 etc usage
> - Update branding to "TomEE" from "OpenEJB"
> - Ensure each has a title
> - Check links
>
> To get there I just need to 1) minimally improve the index pages to have
> groups and 2) add the jbake headers to all the files
>
> After that everyone can start hacking on docs too. Then I'll move on to
> seeing if we can get javadoc generated and published as part of all this.
> Then we'll be able to reference them in our docs, which will be very handy
> and also provide some motivation to actually write javadoc in the first place
> :)
>
>
> -David
>
