tomee-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Jencks <david.a.jen...@gmail.com>
Subject Re: Draft Proposal for overall website direction
Date Wed, 19 Feb 2020 17:17:07 GMT
I was more or less assuming that before reorganizing the website content, organizing it was
required.  Otherwise, you could just drop all current content and start over, which admittedly
might be faster and more satisfactory.

The asciidoctor-maven-plugin is only usable if you want a site with only one version.  All
of the sites you note below indeed only have one version.  Although primitive, what David
Blevins came up with in tomee-site-generator at least allows multiple versions.

For me, two hard requirements would be:
- generate the entire site in one action.  I think this is needed to track what is supposed
to be there and avoid orphaned content like we have now.
- support multiple components and versions with easy navigation between them.  At a minimum,
I think there can be general version less information and version specific information.  Separating
content into perhaps a User Guide and a Reference Guide would be even better.

Here are some Antora generated sites:

Customized UI:
https://camel.apache.org/manual/latest/getting-started.html / https://github.com/apache/camel/tree/master/docs
https://isis.apache.org/guides/ugfun/ugfun.html (using rather non-standard navigation; I find
this confusing) /https://github.com/apache/isis/tree/master/antora (I think this is far too
complicated, but it’s one approach to organizing a gigantic disorganized set of documentation)
https://docs.couchbase.com/server/6.5/introduction/intro.html / https://github.com/couchbase/docs-site
https://www.uyuni-project.org/uyuni-docs/uyuni/index.html / https://github.com/uyuni-project/uyuni-docs

Unmodified UI
https://books.japila.pl/apache-spark-internals/apache-spark-internals/latest/index.html /
https://github.com/japila-books/apache-spark-internals

There’s a list of more sites here:

https://gitlab.com/antora/antora.org/issues/20

Some of these sites, for reasons I don’t understand, avoid making it clear that there are
multiple components and versions.  In the default UI, and several of these sites, at the lower
left there’s a component selector allowing you to choose which component/version you want
to look at.

This is also visible in my preview site.

I’m not aware of any other comparable system that provides built in this level of organization.

David Jencks

> On Feb 19, 2020, at 5:24 AM, gilbertoca <gilbertoca@gmail.com> wrote:
> 
> David Blevins-2 wrote
>> There's an entire facet of this discussion we probably should be talking
>> about which is how to deal with our heaps of content in various states of
>> health; how did it get unhealthy, how do we deal with it, how do we
>> prevent it, how do we encourage more contribution to main docs.
>> 
>> I think any tool in the hands of someone willing to lead an effort to
>> improve our main docs is a good tool.
>> 
>> -David
> 
> We could follow (again) apache friends and others [1] condensing all
> relevant content in something like a User Guide or Reference Guide - that
> would help the Maintenance and contribution. This organization can reduce
> the tooling and it easy integrate(asciidoctor-maven-plugin?) in build
> system[2].
> 
> [1]
> https://netbeans.apache.org/kb/docs/java/index.html
> https://ci.apache.org/projects/wicket/guide/8.x/single.html
> https://beanvalidation.org/2.0/spec/
> https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html
> https://shiro.apache.org/reference.html
> 
> [2] https://asciidoctor.org/docs/asciidoctor-maven-plugin/
> 
> Regards,
> 
> Gilberto
> 
> 
> 
> --
> Sent from: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html


Mime
View raw message