TomEE Documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

TomEE Documentation

ivanjunckes
Hello TomEE developers,

I think it is a bit to hard to find documentation on the website today. I
downloaded site-tomee-ng based on the tutorial added here "Contribute the
this website". Now it runs fine in my machine and it is easy to test
changes (thx Romain!).

I was thinking that the division Admin, Developers and Advanced usages is a
bit confusing. They are all "Documentation", and maybe we should aggregate
them in the same section. This would make clear to the user that is looking
for documentation where to click and search what he is looking for.
Sometimes is a bit confusing for the developers to be clicking around based
on that division trying to find specific things.

I was thinking to do this modification myself to try to make things clear
 in the website, what you guys think?

I think documentation is a high importance item and not having a link
explicitly with it may lead the user to think there is no documentation,
which is not true.

Let me know your thoughts.

Thank you.
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

Romain Manni-Bucau
Hi Ivan


2017-06-11 16:37 GMT+02:00 Ivan Junckes Filho <[hidden email]>:

> Hello TomEE developers,
>
> I think it is a bit to hard to find documentation on the website today. I
> downloaded site-tomee-ng based on the tutorial added here "Contribute the
> this website". Now it runs fine in my machine and it is easy to test
> changes (thx Romain!).
>

Happy it works for somebody else, always the hardest step :)


>
> I was thinking that the division Admin, Developers and Advanced usages is a
> bit confusing. They are all "Documentation", and maybe we should aggregate
> them in the same section. This would make clear to the user that is looking
> for documentation where to click and search what he is looking for.
> Sometimes is a bit confusing for the developers to be clicking around based
> on that division trying to find specific things.
>

Hmm, was done this way cause it was confusing before :s. Admin was clearly
a huge win, dev can need to check admin which can be confusing but still
looks like a win to me.


>
> I was thinking to do this modification myself to try to make things clear
>  in the website, what you guys think?
>

That's the way to go! I'm trying to get it proxied on github but not yet
functional (should be at https://github.com/apache/tomee-site-ng /
https://issues.apache.org/jira/browse/INFRA-14249 for details)


>
> I think documentation is a high importance item and not having a link
> explicitly with it may lead the user to think there is no documentation,
> which is not true.
>

Not sure what you meant here, you want a "documentation" link? This would
basically self-link the site on its home in our case no?


>
> Let me know your thoughts.
>

I think it is important to get such a feedback and enhance the doc as much
as possible (our refcard is not linked for instance -
https://tomee.apache.org/refcard/refcard.html ) but please also keep in
mind we just worked on revamping the whole website and people I spoke with
looked rather happy about it (read it as "we'll not redo it within the year
probably" or completly change it).

To be accurate maybe let us know the way you access the doc. The site was
more or less designed as a fast reference guide accessible from anywhere,
we can kind of index it and make it more searchable if needed, change the
indexation a bit (without completely breaking the structure) if it helps.

From my experience users access the website in 2-3 ways;

1. direct way google 'i have this issues'  =>
tomee.apache.org/page/which/solves/this-problem.html
2. learning way: let see what is tomee? => here our categories are not bad
and allows to not spend 1 week to learn about tomee
3. overview way: we probably need some better getting started and work
around the examples page

One thing I - personally - found very hard was to embrace all tomee in a
single doc cause of its multi flavors nature it doesn't fit a single doc
but splitting it would make it even worse cause you would repeat yourself
enough to make it boring to read so after several tries and retries current
website was an interesting structure (doesn't mean we can't enhance it,
just trying to share how we ended up here and what was the challenge
leading to that outcome).


>
> Thank you.
>

Hope it helps ;)
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

ivanjunckes
What I was trying to say is that if you go to Wildfly, Payara, Liberty WAS
or Tomcat websites for example you may find the distinguish between admin
and developer inside the "Documentation" section. And also as the user I
will never know what is "Advanced" so I will need to click around trying to
find if what I am looking for is advanced or not.

Users who enter the site will mostly think:
1 - "Where is the documentation?" -> Documentation
2 - "How can I download it?" -> Downloads
3 - "How can I contribute?" -> Community

So my proposal is to have in the menu:

Documentation | Examples | Downloads | Community | Security | Blog (Order
is based on what I think people will want to know more, so probably
documentation)

rather than
Admin | Developer | Advanced | Examples | Security | Blog | Community |
Downloads

I think these are the main questions done by users when joining the
website, so I think we should have a very easy explicit link (item in the
menu) for each one of these questions.

Inside documentation we could have it separated by Admin and Developer, I
think it makes more sense this way. What do you think?

Question: If I want to submit PRs in this mirror you mentioned. Am I able
to do that today?

Thanks.

On Sun, Jun 11, 2017 at 4:36 PM, Romain Manni-Bucau <[hidden email]>
wrote:

> Hi Ivan
>
>
> 2017-06-11 16:37 GMT+02:00 Ivan Junckes Filho <[hidden email]>:
>
> > Hello TomEE developers,
> >
> > I think it is a bit to hard to find documentation on the website today. I
> > downloaded site-tomee-ng based on the tutorial added here "Contribute the
> > this website". Now it runs fine in my machine and it is easy to test
> > changes (thx Romain!).
> >
>
> Happy it works for somebody else, always the hardest step :)
>
>
> >
> > I was thinking that the division Admin, Developers and Advanced usages
> is a
> > bit confusing. They are all "Documentation", and maybe we should
> aggregate
> > them in the same section. This would make clear to the user that is
> looking
> > for documentation where to click and search what he is looking for.
> > Sometimes is a bit confusing for the developers to be clicking around
> based
> > on that division trying to find specific things.
> >
>
> Hmm, was done this way cause it was confusing before :s. Admin was clearly
> a huge win, dev can need to check admin which can be confusing but still
> looks like a win to me.
>
>
> >
> > I was thinking to do this modification myself to try to make things clear
> >  in the website, what you guys think?
> >
>
> That's the way to go! I'm trying to get it proxied on github but not yet
> functional (should be at https://github.com/apache/tomee-site-ng /
> https://issues.apache.org/jira/browse/INFRA-14249 for details)
>
>
> >
> > I think documentation is a high importance item and not having a link
> > explicitly with it may lead the user to think there is no documentation,
> > which is not true.
> >
>
> Not sure what you meant here, you want a "documentation" link? This would
> basically self-link the site on its home in our case no?
>
>
> >
> > Let me know your thoughts.
> >
>
> I think it is important to get such a feedback and enhance the doc as much
> as possible (our refcard is not linked for instance -
> https://tomee.apache.org/refcard/refcard.html ) but please also keep in
> mind we just worked on revamping the whole website and people I spoke with
> looked rather happy about it (read it as "we'll not redo it within the year
> probably" or completly change it).
>
> To be accurate maybe let us know the way you access the doc. The site was
> more or less designed as a fast reference guide accessible from anywhere,
> we can kind of index it and make it more searchable if needed, change the
> indexation a bit (without completely breaking the structure) if it helps.
>
> From my experience users access the website in 2-3 ways;
>
> 1. direct way google 'i have this issues'  =>
> tomee.apache.org/page/which/solves/this-problem.html
> 2. learning way: let see what is tomee? => here our categories are not bad
> and allows to not spend 1 week to learn about tomee
> 3. overview way: we probably need some better getting started and work
> around the examples page
>
> One thing I - personally - found very hard was to embrace all tomee in a
> single doc cause of its multi flavors nature it doesn't fit a single doc
> but splitting it would make it even worse cause you would repeat yourself
> enough to make it boring to read so after several tries and retries current
> website was an interesting structure (doesn't mean we can't enhance it,
> just trying to share how we ended up here and what was the challenge
> leading to that outcome).
>
>
> >
> > Thank you.
> >
>
> Hope it helps ;)
>
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

Romain Manni-Bucau
Le 11 juin 2017 22:25, "Ivan Junckes Filho" <[hidden email]> a
écrit :

What I was trying to say is that if you go to Wildfly, Payara, Liberty WAS
or Tomcat websites for example you may find the distinguish between admin
and developer inside the "Documentation" section. And also as the user I
will never know what is "Advanced" so I will need to click around trying to
find if what I am looking for is advanced or not.

Users who enter the site will mostly think:
1 - "Where is the documentation?" -> Documentation
2 - "How can I download it?" -> Downloads
3 - "How can I contribute?" -> Community

So my proposal is to have in the menu:

Documentation | Examples | Downloads | Community | Security | Blog (Order
is based on what I think people will want to know more, so probably
documentation)

rather than
Admin | Developer | Advanced | Examples | Security | Blog | Community |
Downloads

I think these are the main questions done by users when joining the
website, so I think we should have a very easy explicit link (item in the
menu) for each one of these questions.

Inside documentation we could have it separated by Admin and Developer, I
think it makes more sense this way. What do you think?


Well, as said we went from here and moved to current one cause users didnt
like previous one which was exactly what you described of "advanced" if you
think about it so not sure.

Also think about "what is the doc". This sentence doesnt lead anywhere by
definition but "how do i install", "how do i configure", "how do i test"
etc do and lead to current structure.

Wdyt?


Question: If I want to submit PRs in this mirror you mentioned. Am I able
to do that today?



Not yet, we still have an issue on the mirror - in progress bit hope it
will be working soon.


Thanks.

On Sun, Jun 11, 2017 at 4:36 PM, Romain Manni-Bucau <[hidden email]>
wrote:

> Hi Ivan
>
>
> 2017-06-11 16:37 GMT+02:00 Ivan Junckes Filho <[hidden email]>:
>
> > Hello TomEE developers,
> >
> > I think it is a bit to hard to find documentation on the website today.
I
> > downloaded site-tomee-ng based on the tutorial added here "Contribute
the

> > this website". Now it runs fine in my machine and it is easy to test
> > changes (thx Romain!).
> >
>
> Happy it works for somebody else, always the hardest step :)
>
>
> >
> > I was thinking that the division Admin, Developers and Advanced usages
> is a
> > bit confusing. They are all "Documentation", and maybe we should
> aggregate
> > them in the same section. This would make clear to the user that is
> looking
> > for documentation where to click and search what he is looking for.
> > Sometimes is a bit confusing for the developers to be clicking around
> based
> > on that division trying to find specific things.
> >
>
> Hmm, was done this way cause it was confusing before :s. Admin was clearly
> a huge win, dev can need to check admin which can be confusing but still
> looks like a win to me.
>
>
> >
> > I was thinking to do this modification myself to try to make things
clear

> >  in the website, what you guys think?
> >
>
> That's the way to go! I'm trying to get it proxied on github but not yet
> functional (should be at https://github.com/apache/tomee-site-ng /
> https://issues.apache.org/jira/browse/INFRA-14249 for details)
>
>
> >
> > I think documentation is a high importance item and not having a link
> > explicitly with it may lead the user to think there is no documentation,
> > which is not true.
> >
>
> Not sure what you meant here, you want a "documentation" link? This would
> basically self-link the site on its home in our case no?
>
>
> >
> > Let me know your thoughts.
> >
>
> I think it is important to get such a feedback and enhance the doc as much
> as possible (our refcard is not linked for instance -
> https://tomee.apache.org/refcard/refcard.html ) but please also keep in
> mind we just worked on revamping the whole website and people I spoke with
> looked rather happy about it (read it as "we'll not redo it within the
year

> probably" or completly change it).
>
> To be accurate maybe let us know the way you access the doc. The site was
> more or less designed as a fast reference guide accessible from anywhere,
> we can kind of index it and make it more searchable if needed, change the
> indexation a bit (without completely breaking the structure) if it helps.
>
> From my experience users access the website in 2-3 ways;
>
> 1. direct way google 'i have this issues'  =>
> tomee.apache.org/page/which/solves/this-problem.html
> 2. learning way: let see what is tomee? => here our categories are not bad
> and allows to not spend 1 week to learn about tomee
> 3. overview way: we probably need some better getting started and work
> around the examples page
>
> One thing I - personally - found very hard was to embrace all tomee in a
> single doc cause of its multi flavors nature it doesn't fit a single doc
> but splitting it would make it even worse cause you would repeat yourself
> enough to make it boring to read so after several tries and retries
current

> website was an interesting structure (doesn't mean we can't enhance it,
> just trying to share how we ended up here and what was the challenge
> leading to that outcome).
>
>
> >
> > Thank you.
> >
>
> Hope it helps ;)
>
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

ivanjunckes
Do you agree that "what is the doc", "how do i install", "how do i
configure", "how do i test" are all part of a global section called
"Documentation"? Why users wouldn't like it?

For Admin | Developer | Advanced user would need to guess where "how to
install is" and probably need to click in different places. Is that in
developer or admin? Who installs tomee? Or "how do I cluster TomEE", is it
in admin or advanced? That driver to confusion, that is my point.

But it was just a suggestion to make the website more clear, because I keep
hearing it is hard to find documentation there.

If there is no way to send PRs, what would be the way to merge changes if I
submit them? Is there any? Is the github code up to date?

Thank you.

On Sun, Jun 11, 2017 at 6:43 PM, Romain Manni-Bucau <[hidden email]>
wrote:

> Le 11 juin 2017 22:25, "Ivan Junckes Filho" <[hidden email]> a
> écrit :
>
> What I was trying to say is that if you go to Wildfly, Payara, Liberty WAS
> or Tomcat websites for example you may find the distinguish between admin
> and developer inside the "Documentation" section. And also as the user I
> will never know what is "Advanced" so I will need to click around trying to
> find if what I am looking for is advanced or not.
>
> Users who enter the site will mostly think:
> 1 - "Where is the documentation?" -> Documentation
> 2 - "How can I download it?" -> Downloads
> 3 - "How can I contribute?" -> Community
>
> So my proposal is to have in the menu:
>
> Documentation | Examples | Downloads | Community | Security | Blog (Order
> is based on what I think people will want to know more, so probably
> documentation)
>
> rather than
> Admin | Developer | Advanced | Examples | Security | Blog | Community |
> Downloads
>
> I think these are the main questions done by users when joining the
> website, so I think we should have a very easy explicit link (item in the
> menu) for each one of these questions.
>
> Inside documentation we could have it separated by Admin and Developer, I
> think it makes more sense this way. What do you think?
>
>
> Well, as said we went from here and moved to current one cause users didnt
> like previous one which was exactly what you described of "advanced" if you
> think about it so not sure.
>
> Also think about "what is the doc". This sentence doesnt lead anywhere by
> definition but "how do i install", "how do i configure", "how do i test"
> etc do and lead to current structure.
>
> Wdyt?
>
>
> Question: If I want to submit PRs in this mirror you mentioned. Am I able
> to do that today?
>
>
>
> Not yet, we still have an issue on the mirror - in progress bit hope it
> will be working soon.
>
>
> Thanks.
>
> On Sun, Jun 11, 2017 at 4:36 PM, Romain Manni-Bucau <[hidden email]
> >
> wrote:
>
> > Hi Ivan
> >
> >
> > 2017-06-11 16:37 GMT+02:00 Ivan Junckes Filho <[hidden email]>:
> >
> > > Hello TomEE developers,
> > >
> > > I think it is a bit to hard to find documentation on the website today.
> I
> > > downloaded site-tomee-ng based on the tutorial added here "Contribute
> the
> > > this website". Now it runs fine in my machine and it is easy to test
> > > changes (thx Romain!).
> > >
> >
> > Happy it works for somebody else, always the hardest step :)
> >
> >
> > >
> > > I was thinking that the division Admin, Developers and Advanced usages
> > is a
> > > bit confusing. They are all "Documentation", and maybe we should
> > aggregate
> > > them in the same section. This would make clear to the user that is
> > looking
> > > for documentation where to click and search what he is looking for.
> > > Sometimes is a bit confusing for the developers to be clicking around
> > based
> > > on that division trying to find specific things.
> > >
> >
> > Hmm, was done this way cause it was confusing before :s. Admin was
> clearly
> > a huge win, dev can need to check admin which can be confusing but still
> > looks like a win to me.
> >
> >
> > >
> > > I was thinking to do this modification myself to try to make things
> clear
> > >  in the website, what you guys think?
> > >
> >
> > That's the way to go! I'm trying to get it proxied on github but not yet
> > functional (should be at https://github.com/apache/tomee-site-ng /
> > https://issues.apache.org/jira/browse/INFRA-14249 for details)
> >
> >
> > >
> > > I think documentation is a high importance item and not having a link
> > > explicitly with it may lead the user to think there is no
> documentation,
> > > which is not true.
> > >
> >
> > Not sure what you meant here, you want a "documentation" link? This would
> > basically self-link the site on its home in our case no?
> >
> >
> > >
> > > Let me know your thoughts.
> > >
> >
> > I think it is important to get such a feedback and enhance the doc as
> much
> > as possible (our refcard is not linked for instance -
> > https://tomee.apache.org/refcard/refcard.html ) but please also keep in
> > mind we just worked on revamping the whole website and people I spoke
> with
> > looked rather happy about it (read it as "we'll not redo it within the
> year
> > probably" or completly change it).
> >
> > To be accurate maybe let us know the way you access the doc. The site was
> > more or less designed as a fast reference guide accessible from anywhere,
> > we can kind of index it and make it more searchable if needed, change the
> > indexation a bit (without completely breaking the structure) if it helps.
> >
> > From my experience users access the website in 2-3 ways;
> >
> > 1. direct way google 'i have this issues'  =>
> > tomee.apache.org/page/which/solves/this-problem.html
> > 2. learning way: let see what is tomee? => here our categories are not
> bad
> > and allows to not spend 1 week to learn about tomee
> > 3. overview way: we probably need some better getting started and work
> > around the examples page
> >
> > One thing I - personally - found very hard was to embrace all tomee in a
> > single doc cause of its multi flavors nature it doesn't fit a single doc
> > but splitting it would make it even worse cause you would repeat yourself
> > enough to make it boring to read so after several tries and retries
> current
> > website was an interesting structure (doesn't mean we can't enhance it,
> > just trying to share how we ended up here and what was the challenge
> > leading to that outcome).
> >
> >
> > >
> > > Thank you.
> > >
> >
> > Hope it helps ;)
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

Romain Manni-Bucau
Le 24 juin 2017 16:01, "Ivan Junckes Filho" <[hidden email]> a
écrit :

Do you agree that "what is the doc", "how do i install", "how do i
configure", "how do i test" are all part of a global section called
"Documentation"? Why users wouldn't like it?


You mix doc and getting started"s". A getting started is part of the doc
but is an optional part whereas doc covers all topics. We can add a getting
started entries referencing related pages if needed which would solve your
issue without adding back some confusion pby.



For Admin | Developer | Advanced user would need to guess where "how to
install is" and probably need to click in different places. Is that in
developer or admin? Who installs tomee? Or "how do I cluster TomEE", is it
in admin or advanced? That driver to confusion, that is my point.



Get back to one of my previous point. You assume you enter the website with
such a question which is maybe 10% of the cases and we cant solve them all
until we impl a great search engine. Being too specific will lead you to a
sitemap which is pretty unusable from the feedback we got before current
site.


But it was just a suggestion to make the website more clear, because I keep
hearing it is hard to find documentation there.


It is better since we have this new website, pby some work on the search.
To be transparent it is the first time i get positive feedbacks and not
much negative since i work with openejb (3 websites) so a new one would
need to bring more and no regression.




If there is no way to send PRs, what would be the way to merge changes if I
submit them? Is there any? Is the github code up to date?


It is pending but a patch attached to a jira always works.


Thank you.

On Sun, Jun 11, 2017 at 6:43 PM, Romain Manni-Bucau <[hidden email]>
wrote:

> Le 11 juin 2017 22:25, "Ivan Junckes Filho" <[hidden email]> a
> écrit :
>
> What I was trying to say is that if you go to Wildfly, Payara, Liberty WAS
> or Tomcat websites for example you may find the distinguish between admin
> and developer inside the "Documentation" section. And also as the user I
> will never know what is "Advanced" so I will need to click around trying
to

> find if what I am looking for is advanced or not.
>
> Users who enter the site will mostly think:
> 1 - "Where is the documentation?" -> Documentation
> 2 - "How can I download it?" -> Downloads
> 3 - "How can I contribute?" -> Community
>
> So my proposal is to have in the menu:
>
> Documentation | Examples | Downloads | Community | Security | Blog (Order
> is based on what I think people will want to know more, so probably
> documentation)
>
> rather than
> Admin | Developer | Advanced | Examples | Security | Blog | Community |
> Downloads
>
> I think these are the main questions done by users when joining the
> website, so I think we should have a very easy explicit link (item in the
> menu) for each one of these questions.
>
> Inside documentation we could have it separated by Admin and Developer, I
> think it makes more sense this way. What do you think?
>
>
> Well, as said we went from here and moved to current one cause users didnt
> like previous one which was exactly what you described of "advanced" if
you

> think about it so not sure.
>
> Also think about "what is the doc". This sentence doesnt lead anywhere by
> definition but "how do i install", "how do i configure", "how do i test"
> etc do and lead to current structure.
>
> Wdyt?
>
>
> Question: If I want to submit PRs in this mirror you mentioned. Am I able
> to do that today?
>
>
>
> Not yet, we still have an issue on the mirror - in progress bit hope it
> will be working soon.
>
>
> Thanks.
>
> On Sun, Jun 11, 2017 at 4:36 PM, Romain Manni-Bucau <[hidden email]
> >
> wrote:
>
> > Hi Ivan
> >
> >
> > 2017-06-11 16:37 GMT+02:00 Ivan Junckes Filho <[hidden email]>:
> >
> > > Hello TomEE developers,
> > >
> > > I think it is a bit to hard to find documentation on the website
today.

> I
> > > downloaded site-tomee-ng based on the tutorial added here "Contribute
> the
> > > this website". Now it runs fine in my machine and it is easy to test
> > > changes (thx Romain!).
> > >
> >
> > Happy it works for somebody else, always the hardest step :)
> >
> >
> > >
> > > I was thinking that the division Admin, Developers and Advanced usages
> > is a
> > > bit confusing. They are all "Documentation", and maybe we should
> > aggregate
> > > them in the same section. This would make clear to the user that is
> > looking
> > > for documentation where to click and search what he is looking for.
> > > Sometimes is a bit confusing for the developers to be clicking around
> > based
> > > on that division trying to find specific things.
> > >
> >
> > Hmm, was done this way cause it was confusing before :s. Admin was
> clearly
> > a huge win, dev can need to check admin which can be confusing but still
> > looks like a win to me.
> >
> >
> > >
> > > I was thinking to do this modification myself to try to make things
> clear
> > >  in the website, what you guys think?
> > >
> >
> > That's the way to go! I'm trying to get it proxied on github but not yet
> > functional (should be at https://github.com/apache/tomee-site-ng /
> > https://issues.apache.org/jira/browse/INFRA-14249 for details)
> >
> >
> > >
> > > I think documentation is a high importance item and not having a link
> > > explicitly with it may lead the user to think there is no
> documentation,
> > > which is not true.
> > >
> >
> > Not sure what you meant here, you want a "documentation" link? This
would

> > basically self-link the site on its home in our case no?
> >
> >
> > >
> > > Let me know your thoughts.
> > >
> >
> > I think it is important to get such a feedback and enhance the doc as
> much
> > as possible (our refcard is not linked for instance -
> > https://tomee.apache.org/refcard/refcard.html ) but please also keep in
> > mind we just worked on revamping the whole website and people I spoke
> with
> > looked rather happy about it (read it as "we'll not redo it within the
> year
> > probably" or completly change it).
> >
> > To be accurate maybe let us know the way you access the doc. The site
was
> > more or less designed as a fast reference guide accessible from
anywhere,
> > we can kind of index it and make it more searchable if needed, change
the
> > indexation a bit (without completely breaking the structure) if it
helps.

> >
> > From my experience users access the website in 2-3 ways;
> >
> > 1. direct way google 'i have this issues'  =>
> > tomee.apache.org/page/which/solves/this-problem.html
> > 2. learning way: let see what is tomee? => here our categories are not
> bad
> > and allows to not spend 1 week to learn about tomee
> > 3. overview way: we probably need some better getting started and work
> > around the examples page
> >
> > One thing I - personally - found very hard was to embrace all tomee in a
> > single doc cause of its multi flavors nature it doesn't fit a single doc
> > but splitting it would make it even worse cause you would repeat
yourself

> > enough to make it boring to read so after several tries and retries
> current
> > website was an interesting structure (doesn't mean we can't enhance it,
> > just trying to share how we ended up here and what was the challenge
> > leading to that outcome).
> >
> >
> > >
> > > Thank you.
> > >
> >
> > Hope it helps ;)
> >
>
Reply | Threaded
Open this post in threaded view
|

RE: TomEE Documentation

Thomas Whitmore
In reply to this post by ivanjunckes
Hi Ivan, Romain,

I probably support having a 'Documentation' item in the top menu.  At the moment there are all the subtopics, but nothing at the top-level says Documentation!  At a brief glance this is likely to give the impression that there isn't documentation, or that it's hard to find.

From an external perspective 'Documentation', 'Getting Started' and possibly 'Examples' are good top-level headings.

I would suggest something like:
- Documentation
- Getting Starting
- Examples
- Blog
- Community
- Downloads

I write quite a lot of documentation so my quick thoughts -- trying to be constructive here.

Reviewing the current 'Developer', 'Admin', 'Advanced' pages -- these are all lacking any overview to tell you the basics and badly empty.
There needs to be some introductory text to start these sections and set the scene,  TomEE for Developers needs to start with an overview of what TomEE is & why it's good;  then have some simple guide or guides to writing JEE application, as the first (few) articles. These will show how to use TomEE's features.

'Developer' section should go something like:
- (introductory text)  TomEE is a JEE container. Advantages this gives.
- JEE Basics  -- basic outlines of how to write a JEE application & link to other guides
- Eclipse, Intellij Idea, Netbeans: TomEE in and IDE   (maybe:  but there's no real content here)
- JEE Feature Guides
- TomEE and Testing  

Perhaps there could be several guides to important JEE areas:
- JEE Guide -- CDI
- JEE Guide -- Datasource
- JEE Guide -- JPA
- JEE Guide -- EJB
- JEE Guide -- CXF & Webservices

The above topics map well to the areas in Examples http://tomee.apache.org/examples/index-ng.html which have good coverage of examples.. and outlining a little bit of concrete usage should allow good opportunities to explain TomEE's configuration, particular details etc.

(Little bit of an insight here -- perhaps the fact that we haven't been focusing / docing based on the JEE features, has made it hard to write doc?)

I suggest 'Developer' section should not start with "All you need to know about TomEE classloading". This is not what new developer should need to get started with, and is a great way to scare people off.

Busy these past couple of months, trying to offer some guidance to the best degree I can but don't have time available to actually do the writing.


Regards,
Thomas

______________________________________________________________________
This email has been scanned by the Symantec Email Security.cloud service.
For more information please visit http://www.symanteccloud.com
______________________________________________________________________
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

Romain Manni-Bucau
Hmm, interesting. Reworking the website I ensured to avoid JavaEE (BTW JEE
doesnt exist anymore ;)) cause it is not important at tomee level. I mean
if tomee covers JavaEE then it reduces mathematically tomee specific
features space which is what users search coming on tomee website in
general.

The classloader point is funny but part of the most hit issue so don't know
if hiding it a bit would be beneficial. The website has been thought as an
enabler/reference and less like a book with a progression ('getting
started"s probably) which is more or less what you propose. Wonder if we
can merge both somehow, probably with the new menu item.

I like your menu but it can need a submenu on doc - not sure how mobile
handling would be but doable.

Maybe we should drop the blog, we never used it accurately.


Romain Manni-Bucau
@rmannibucau <https://twitter.com/rmannibucau> |  Blog
<https://blog-rmannibucau.rhcloud.com> | Old Blog
<http://rmannibucau.wordpress.com> | Github <https://github.com/rmannibucau> |
LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
<https://javaeefactory-rmannibucau.rhcloud.com>

2017-06-26 0:40 GMT+02:00 Thomas Whitmore <[hidden email]>:

> Hi Ivan, Romain,
>
> I probably support having a 'Documentation' item in the top menu.  At the
> moment there are all the subtopics, but nothing at the top-level says
> Documentation!  At a brief glance this is likely to give the impression
> that there isn't documentation, or that it's hard to find.
>
> From an external perspective 'Documentation', 'Getting Started' and
> possibly 'Examples' are good top-level headings.
>
> I would suggest something like:
> - Documentation
> - Getting Starting
> - Examples
> - Blog
> - Community
> - Downloads
>
> I write quite a lot of documentation so my quick thoughts -- trying to be
> constructive here.
>
> Reviewing the current 'Developer', 'Admin', 'Advanced' pages -- these are
> all lacking any overview to tell you the basics and badly empty.
> There needs to be some introductory text to start these sections and set
> the scene,  TomEE for Developers needs to start with an overview of what
> TomEE is & why it's good;  then have some simple guide or guides to writing
> JEE application, as the first (few) articles. These will show how to use
> TomEE's features.
>
> 'Developer' section should go something like:
> - (introductory text)  TomEE is a JEE container. Advantages this gives.
> - JEE Basics  -- basic outlines of how to write a JEE application & link
> to other guides
> - Eclipse, Intellij Idea, Netbeans: TomEE in and IDE   (maybe:  but
> there's no real content here)
> - JEE Feature Guides
> - TomEE and Testing
>
> Perhaps there could be several guides to important JEE areas:
> - JEE Guide -- CDI
> - JEE Guide -- Datasource
> - JEE Guide -- JPA
> - JEE Guide -- EJB
> - JEE Guide -- CXF & Webservices
>
> The above topics map well to the areas in Examples
> http://tomee.apache.org/examples/index-ng.html which have good coverage
> of examples.. and outlining a little bit of concrete usage should allow
> good opportunities to explain TomEE's configuration, particular details etc.
>
> (Little bit of an insight here -- perhaps the fact that we haven't been
> focusing / docing based on the JEE features, has made it hard to write doc?)
>
> I suggest 'Developer' section should not start with "All you need to know
> about TomEE classloading". This is not what new developer should need to
> get started with, and is a great way to scare people off.
>
> Busy these past couple of months, trying to offer some guidance to the
> best degree I can but don't have time available to actually do the writing.
>
>
> Regards,
> Thomas
>
> ______________________________________________________________________
> This email has been scanned by the Symantec Email Security.cloud service.
> For more information please visit http://www.symanteccloud.com
> ______________________________________________________________________
>
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

ivanjunckes
On Mon, Jun 26, 2017 at 2:16 AM, Romain Manni-Bucau <[hidden email]>
wrote:

> Hmm, interesting. Reworking the website I ensured to avoid JavaEE (BTW JEE
> doesnt exist anymore ;)) cause it is not important at tomee level. I mean
> if tomee covers JavaEE then it reduces mathematically tomee specific
> features space which is what users search coming on tomee website in
> general.
>
> The classloader point is funny but part of the most hit issue so don't know
> if hiding it a bit would be beneficial. The website has been thought as an
> enabler/reference and less like a book with a progression ('getting
> started"s probably) which is more or less what you propose. Wonder if we
> can merge both somehow, probably with the new menu item.
>
> I like your menu but it can need a submenu on doc - not sure how mobile
> handling would be but doable.
>
> Maybe we should drop the blog, we never used it accurately.
>
>
> Romain Manni-Bucau
> @rmannibucau <https://twitter.com/rmannibucau> |  Blog
> <https://blog-rmannibucau.rhcloud.com> | Old Blog
> <http://rmannibucau.wordpress.com> | Github <https://github.com/
> rmannibucau> |
> LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
> <https://javaeefactory-rmannibucau.rhcloud.com>
>
> 2017-06-26 0:40 GMT+02:00 Thomas Whitmore <[hidden email]
> >:
>
> > Hi Ivan, Romain,
> >
> > I probably support having a 'Documentation' item in the top menu.  At the
> > moment there are all the subtopics, but nothing at the top-level says
> > Documentation!  At a brief glance this is likely to give the impression
> > that there isn't documentation, or that it's hard to find.
> >
> > From an external perspective 'Documentation', 'Getting Started' and
> > possibly 'Examples' are good top-level headings.
> >
> > I would suggest something like:
> > - Documentation
> > - Getting Starting
> > - Examples
> > - Blog
> > - Community
> > - Downloads
> >
> > I write quite a lot of documentation so my quick thoughts -- trying to be
> > constructive here.
> >
> > Reviewing the current 'Developer', 'Admin', 'Advanced' pages -- these are
> > all lacking any overview to tell you the basics and badly empty.
> > There needs to be some introductory text to start these sections and set
> > the scene,  TomEE for Developers needs to start with an overview of what
> > TomEE is & why it's good;  then have some simple guide or guides to
> writing
> > JEE application, as the first (few) articles. These will show how to use
> > TomEE's features.
> >
> > 'Developer' section should go something like:
> > - (introductory text)  TomEE is a JEE container. Advantages this gives.
> > - JEE Basics  -- basic outlines of how to write a JEE application & link
> > to other guides
> > - Eclipse, Intellij Idea, Netbeans: TomEE in and IDE   (maybe:  but
> > there's no real content here)
> > - JEE Feature Guides
> > - TomEE and Testing
> >
> > Perhaps there could be several guides to important JEE areas:
> > - JEE Guide -- CDI
> > - JEE Guide -- Datasource
> > - JEE Guide -- JPA
> > - JEE Guide -- EJB
> > - JEE Guide -- CXF & Webservices
> >
> > The above topics map well to the areas in Examples
> > http://tomee.apache.org/examples/index-ng.html which have good coverage
> > of examples.. and outlining a little bit of concrete usage should allow
> > good opportunities to explain TomEE's configuration, particular details
> etc.
> >
> > (Little bit of an insight here -- perhaps the fact that we haven't been
> > focusing / docing based on the JEE features, has made it hard to write
> doc?)
> >
> > I suggest 'Developer' section should not start with "All you need to know
> > about TomEE classloading". This is not what new developer should need to
> > get started with, and is a great way to scare people off.
> >
> > Busy these past couple of months, trying to offer some guidance to the
> > best degree I can but don't have time available to actually do the
> writing.
> >
> >
> > Regards,
> > Thomas
> >
> > ______________________________________________________________________
> > This email has been scanned by the Symantec Email Security.cloud service.
> > For more information please visit http://www.symanteccloud.com
> > ______________________________________________________________________
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

ivanjunckes
Hi guys, if you agree with Thomas menu I can try to work on the change and
make the "sub-menus" like sections in the page so sub-menus wouldn't be
necessary.

What do you think Romain?



On Mon, Jun 26, 2017 at 7:42 AM, Ivan Junckes Filho <[hidden email]>
wrote:

>
>
> On Mon, Jun 26, 2017 at 2:16 AM, Romain Manni-Bucau <[hidden email]
> > wrote:
>
>> Hmm, interesting. Reworking the website I ensured to avoid JavaEE (BTW JEE
>> doesnt exist anymore ;)) cause it is not important at tomee level. I mean
>> if tomee covers JavaEE then it reduces mathematically tomee specific
>> features space which is what users search coming on tomee website in
>> general.
>>
>> The classloader point is funny but part of the most hit issue so don't
>> know
>> if hiding it a bit would be beneficial. The website has been thought as an
>> enabler/reference and less like a book with a progression ('getting
>> started"s probably) which is more or less what you propose. Wonder if we
>> can merge both somehow, probably with the new menu item.
>>
>> I like your menu but it can need a submenu on doc - not sure how mobile
>> handling would be but doable.
>>
>> Maybe we should drop the blog, we never used it accurately.
>>
>>
>> Romain Manni-Bucau
>> @rmannibucau <https://twitter.com/rmannibucau> |  Blog
>> <https://blog-rmannibucau.rhcloud.com> | Old Blog
>> <http://rmannibucau.wordpress.com> | Github <
>> https://github.com/rmannibucau> |
>> LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
>> <https://javaeefactory-rmannibucau.rhcloud.com>
>>
>> 2017-06-26 0:40 GMT+02:00 Thomas Whitmore <[hidden email]
>> >:
>>
>> > Hi Ivan, Romain,
>> >
>> > I probably support having a 'Documentation' item in the top menu.  At
>> the
>> > moment there are all the subtopics, but nothing at the top-level says
>> > Documentation!  At a brief glance this is likely to give the impression
>> > that there isn't documentation, or that it's hard to find.
>> >
>> > From an external perspective 'Documentation', 'Getting Started' and
>> > possibly 'Examples' are good top-level headings.
>> >
>> > I would suggest something like:
>> > - Documentation
>> > - Getting Starting
>> > - Examples
>> > - Blog
>> > - Community
>> > - Downloads
>> >
>> > I write quite a lot of documentation so my quick thoughts -- trying to
>> be
>> > constructive here.
>> >
>> > Reviewing the current 'Developer', 'Admin', 'Advanced' pages -- these
>> are
>> > all lacking any overview to tell you the basics and badly empty.
>> > There needs to be some introductory text to start these sections and set
>> > the scene,  TomEE for Developers needs to start with an overview of what
>> > TomEE is & why it's good;  then have some simple guide or guides to
>> writing
>> > JEE application, as the first (few) articles. These will show how to use
>> > TomEE's features.
>> >
>> > 'Developer' section should go something like:
>> > - (introductory text)  TomEE is a JEE container. Advantages this gives.
>> > - JEE Basics  -- basic outlines of how to write a JEE application & link
>> > to other guides
>> > - Eclipse, Intellij Idea, Netbeans: TomEE in and IDE   (maybe:  but
>> > there's no real content here)
>> > - JEE Feature Guides
>> > - TomEE and Testing
>> >
>> > Perhaps there could be several guides to important JEE areas:
>> > - JEE Guide -- CDI
>> > - JEE Guide -- Datasource
>> > - JEE Guide -- JPA
>> > - JEE Guide -- EJB
>> > - JEE Guide -- CXF & Webservices
>> >
>> > The above topics map well to the areas in Examples
>> > http://tomee.apache.org/examples/index-ng.html which have good coverage
>> > of examples.. and outlining a little bit of concrete usage should allow
>> > good opportunities to explain TomEE's configuration, particular details
>> etc.
>> >
>> > (Little bit of an insight here -- perhaps the fact that we haven't been
>> > focusing / docing based on the JEE features, has made it hard to write
>> doc?)
>> >
>> > I suggest 'Developer' section should not start with "All you need to
>> know
>> > about TomEE classloading". This is not what new developer should need to
>> > get started with, and is a great way to scare people off.
>> >
>> > Busy these past couple of months, trying to offer some guidance to the
>> > best degree I can but don't have time available to actually do the
>> writing.
>> >
>> >
>> > Regards,
>> > Thomas
>> >
>> > ______________________________________________________________________
>> > This email has been scanned by the Symantec Email Security.cloud
>> service.
>> > For more information please visit http://www.symanteccloud.com
>> > ______________________________________________________________________
>> >
>>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

Romain Manni-Bucau
2017-06-26 12:43 GMT+02:00 Ivan Junckes Filho <[hidden email]>:

> Hi guys, if you agree with Thomas menu I can try to work on the change and
> make the "sub-menus" like sections in the page so sub-menus wouldn't be
> necessary.
>
> What do you think Romain?
>

sub menus are needed to ensure the navigation is smooth and not enforced
some pages (reduce the number of *clicks* ;) - hover is fine).

+1 to modify the menu while it works on desktop and mobile.


>
>
>
> On Mon, Jun 26, 2017 at 7:42 AM, Ivan Junckes Filho <[hidden email]
> >
> wrote:
>
> >
> >
> > On Mon, Jun 26, 2017 at 2:16 AM, Romain Manni-Bucau <
> [hidden email]
> > > wrote:
> >
> >> Hmm, interesting. Reworking the website I ensured to avoid JavaEE (BTW
> JEE
> >> doesnt exist anymore ;)) cause it is not important at tomee level. I
> mean
> >> if tomee covers JavaEE then it reduces mathematically tomee specific
> >> features space which is what users search coming on tomee website in
> >> general.
> >>
> >> The classloader point is funny but part of the most hit issue so don't
> >> know
> >> if hiding it a bit would be beneficial. The website has been thought as
> an
> >> enabler/reference and less like a book with a progression ('getting
> >> started"s probably) which is more or less what you propose. Wonder if we
> >> can merge both somehow, probably with the new menu item.
> >>
> >> I like your menu but it can need a submenu on doc - not sure how mobile
> >> handling would be but doable.
> >>
> >> Maybe we should drop the blog, we never used it accurately.
> >>
> >>
> >> Romain Manni-Bucau
> >> @rmannibucau <https://twitter.com/rmannibucau> |  Blog
> >> <https://blog-rmannibucau.rhcloud.com> | Old Blog
> >> <http://rmannibucau.wordpress.com> | Github <
> >> https://github.com/rmannibucau> |
> >> LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
> >> <https://javaeefactory-rmannibucau.rhcloud.com>
> >>
> >> 2017-06-26 0:40 GMT+02:00 Thomas Whitmore <twhitmore@bravurasolutions.
> com
> >> >:
> >>
> >> > Hi Ivan, Romain,
> >> >
> >> > I probably support having a 'Documentation' item in the top menu.  At
> >> the
> >> > moment there are all the subtopics, but nothing at the top-level says
> >> > Documentation!  At a brief glance this is likely to give the
> impression
> >> > that there isn't documentation, or that it's hard to find.
> >> >
> >> > From an external perspective 'Documentation', 'Getting Started' and
> >> > possibly 'Examples' are good top-level headings.
> >> >
> >> > I would suggest something like:
> >> > - Documentation
> >> > - Getting Starting
> >> > - Examples
> >> > - Blog
> >> > - Community
> >> > - Downloads
> >> >
> >> > I write quite a lot of documentation so my quick thoughts -- trying to
> >> be
> >> > constructive here.
> >> >
> >> > Reviewing the current 'Developer', 'Admin', 'Advanced' pages -- these
> >> are
> >> > all lacking any overview to tell you the basics and badly empty.
> >> > There needs to be some introductory text to start these sections and
> set
> >> > the scene,  TomEE for Developers needs to start with an overview of
> what
> >> > TomEE is & why it's good;  then have some simple guide or guides to
> >> writing
> >> > JEE application, as the first (few) articles. These will show how to
> use
> >> > TomEE's features.
> >> >
> >> > 'Developer' section should go something like:
> >> > - (introductory text)  TomEE is a JEE container. Advantages this
> gives.
> >> > - JEE Basics  -- basic outlines of how to write a JEE application &
> link
> >> > to other guides
> >> > - Eclipse, Intellij Idea, Netbeans: TomEE in and IDE   (maybe:  but
> >> > there's no real content here)
> >> > - JEE Feature Guides
> >> > - TomEE and Testing
> >> >
> >> > Perhaps there could be several guides to important JEE areas:
> >> > - JEE Guide -- CDI
> >> > - JEE Guide -- Datasource
> >> > - JEE Guide -- JPA
> >> > - JEE Guide -- EJB
> >> > - JEE Guide -- CXF & Webservices
> >> >
> >> > The above topics map well to the areas in Examples
> >> > http://tomee.apache.org/examples/index-ng.html which have good
> coverage
> >> > of examples.. and outlining a little bit of concrete usage should
> allow
> >> > good opportunities to explain TomEE's configuration, particular
> details
> >> etc.
> >> >
> >> > (Little bit of an insight here -- perhaps the fact that we haven't
> been
> >> > focusing / docing based on the JEE features, has made it hard to write
> >> doc?)
> >> >
> >> > I suggest 'Developer' section should not start with "All you need to
> >> know
> >> > about TomEE classloading". This is not what new developer should need
> to
> >> > get started with, and is a great way to scare people off.
> >> >
> >> > Busy these past couple of months, trying to offer some guidance to the
> >> > best degree I can but don't have time available to actually do the
> >> writing.
> >> >
> >> >
> >> > Regards,
> >> > Thomas
> >> >
> >> > ____________________________________________________________
> __________
> >> > This email has been scanned by the Symantec Email Security.cloud
> >> service.
> >> > For more information please visit http://www.symanteccloud.com
> >> > ____________________________________________________________
> __________
> >> >
> >>
> >
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

ivanjunckes
Thanks Romain will work on this.

On Mon, Jun 26, 2017 at 7:45 AM, Romain Manni-Bucau <[hidden email]>
wrote:

> 2017-06-26 12:43 GMT+02:00 Ivan Junckes Filho <[hidden email]>:
>
> > Hi guys, if you agree with Thomas menu I can try to work on the change
> and
> > make the "sub-menus" like sections in the page so sub-menus wouldn't be
> > necessary.
> >
> > What do you think Romain?
> >
>
> sub menus are needed to ensure the navigation is smooth and not enforced
> some pages (reduce the number of *clicks* ;) - hover is fine).
>
> +1 to modify the menu while it works on desktop and mobile.
>
>
> >
> >
> >
> > On Mon, Jun 26, 2017 at 7:42 AM, Ivan Junckes Filho <
> [hidden email]
> > >
> > wrote:
> >
> > >
> > >
> > > On Mon, Jun 26, 2017 at 2:16 AM, Romain Manni-Bucau <
> > [hidden email]
> > > > wrote:
> > >
> > >> Hmm, interesting. Reworking the website I ensured to avoid JavaEE (BTW
> > JEE
> > >> doesnt exist anymore ;)) cause it is not important at tomee level. I
> > mean
> > >> if tomee covers JavaEE then it reduces mathematically tomee specific
> > >> features space which is what users search coming on tomee website in
> > >> general.
> > >>
> > >> The classloader point is funny but part of the most hit issue so don't
> > >> know
> > >> if hiding it a bit would be beneficial. The website has been thought
> as
> > an
> > >> enabler/reference and less like a book with a progression ('getting
> > >> started"s probably) which is more or less what you propose. Wonder if
> we
> > >> can merge both somehow, probably with the new menu item.
> > >>
> > >> I like your menu but it can need a submenu on doc - not sure how
> mobile
> > >> handling would be but doable.
> > >>
> > >> Maybe we should drop the blog, we never used it accurately.
> > >>
> > >>
> > >> Romain Manni-Bucau
> > >> @rmannibucau <https://twitter.com/rmannibucau> |  Blog
> > >> <https://blog-rmannibucau.rhcloud.com> | Old Blog
> > >> <http://rmannibucau.wordpress.com> | Github <
> > >> https://github.com/rmannibucau> |
> > >> LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
> > >> <https://javaeefactory-rmannibucau.rhcloud.com>
> > >>
> > >> 2017-06-26 0:40 GMT+02:00 Thomas Whitmore <twhitmore@bravurasolutions.
> > com
> > >> >:
> > >>
> > >> > Hi Ivan, Romain,
> > >> >
> > >> > I probably support having a 'Documentation' item in the top menu.
> At
> > >> the
> > >> > moment there are all the subtopics, but nothing at the top-level
> says
> > >> > Documentation!  At a brief glance this is likely to give the
> > impression
> > >> > that there isn't documentation, or that it's hard to find.
> > >> >
> > >> > From an external perspective 'Documentation', 'Getting Started' and
> > >> > possibly 'Examples' are good top-level headings.
> > >> >
> > >> > I would suggest something like:
> > >> > - Documentation
> > >> > - Getting Starting
> > >> > - Examples
> > >> > - Blog
> > >> > - Community
> > >> > - Downloads
> > >> >
> > >> > I write quite a lot of documentation so my quick thoughts -- trying
> to
> > >> be
> > >> > constructive here.
> > >> >
> > >> > Reviewing the current 'Developer', 'Admin', 'Advanced' pages --
> these
> > >> are
> > >> > all lacking any overview to tell you the basics and badly empty.
> > >> > There needs to be some introductory text to start these sections and
> > set
> > >> > the scene,  TomEE for Developers needs to start with an overview of
> > what
> > >> > TomEE is & why it's good;  then have some simple guide or guides to
> > >> writing
> > >> > JEE application, as the first (few) articles. These will show how to
> > use
> > >> > TomEE's features.
> > >> >
> > >> > 'Developer' section should go something like:
> > >> > - (introductory text)  TomEE is a JEE container. Advantages this
> > gives.
> > >> > - JEE Basics  -- basic outlines of how to write a JEE application &
> > link
> > >> > to other guides
> > >> > - Eclipse, Intellij Idea, Netbeans: TomEE in and IDE   (maybe:  but
> > >> > there's no real content here)
> > >> > - JEE Feature Guides
> > >> > - TomEE and Testing
> > >> >
> > >> > Perhaps there could be several guides to important JEE areas:
> > >> > - JEE Guide -- CDI
> > >> > - JEE Guide -- Datasource
> > >> > - JEE Guide -- JPA
> > >> > - JEE Guide -- EJB
> > >> > - JEE Guide -- CXF & Webservices
> > >> >
> > >> > The above topics map well to the areas in Examples
> > >> > http://tomee.apache.org/examples/index-ng.html which have good
> > coverage
> > >> > of examples.. and outlining a little bit of concrete usage should
> > allow
> > >> > good opportunities to explain TomEE's configuration, particular
> > details
> > >> etc.
> > >> >
> > >> > (Little bit of an insight here -- perhaps the fact that we haven't
> > been
> > >> > focusing / docing based on the JEE features, has made it hard to
> write
> > >> doc?)
> > >> >
> > >> > I suggest 'Developer' section should not start with "All you need to
> > >> know
> > >> > about TomEE classloading". This is not what new developer should
> need
> > to
> > >> > get started with, and is a great way to scare people off.
> > >> >
> > >> > Busy these past couple of months, trying to offer some guidance to
> the
> > >> > best degree I can but don't have time available to actually do the
> > >> writing.
> > >> >
> > >> >
> > >> > Regards,
> > >> > Thomas
> > >> >
> > >> > ____________________________________________________________
> > __________
> > >> > This email has been scanned by the Symantec Email Security.cloud
> > >> service.
> > >> > For more information please visit http://www.symanteccloud.com
> > >> > ____________________________________________________________
> > __________
> > >> >
> > >>
> > >
> > >
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: TomEE Documentation

Romain Manni-Bucau
PS - cause it appeared unobvious on jira: we should try to keep current
bookmarks as much as possible cause users already complained we changed
them and it is now "done" (= we dont get complains anymore or very rarely)
so i don't feel comfortable breaking it again


Romain Manni-Bucau
@rmannibucau <https://twitter.com/rmannibucau> |  Blog
<https://blog-rmannibucau.rhcloud.com> | Old Blog
<http://rmannibucau.wordpress.com> | Github <https://github.com/rmannibucau> |
LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
<https://javaeefactory-rmannibucau.rhcloud.com>

2017-06-26 12:48 GMT+02:00 Ivan Junckes Filho <[hidden email]>:

> Thanks Romain will work on this.
>
> On Mon, Jun 26, 2017 at 7:45 AM, Romain Manni-Bucau <[hidden email]
> >
> wrote:
>
> > 2017-06-26 12:43 GMT+02:00 Ivan Junckes Filho <[hidden email]>:
> >
> > > Hi guys, if you agree with Thomas menu I can try to work on the change
> > and
> > > make the "sub-menus" like sections in the page so sub-menus wouldn't be
> > > necessary.
> > >
> > > What do you think Romain?
> > >
> >
> > sub menus are needed to ensure the navigation is smooth and not enforced
> > some pages (reduce the number of *clicks* ;) - hover is fine).
> >
> > +1 to modify the menu while it works on desktop and mobile.
> >
> >
> > >
> > >
> > >
> > > On Mon, Jun 26, 2017 at 7:42 AM, Ivan Junckes Filho <
> > [hidden email]
> > > >
> > > wrote:
> > >
> > > >
> > > >
> > > > On Mon, Jun 26, 2017 at 2:16 AM, Romain Manni-Bucau <
> > > [hidden email]
> > > > > wrote:
> > > >
> > > >> Hmm, interesting. Reworking the website I ensured to avoid JavaEE
> (BTW
> > > JEE
> > > >> doesnt exist anymore ;)) cause it is not important at tomee level. I
> > > mean
> > > >> if tomee covers JavaEE then it reduces mathematically tomee specific
> > > >> features space which is what users search coming on tomee website in
> > > >> general.
> > > >>
> > > >> The classloader point is funny but part of the most hit issue so
> don't
> > > >> know
> > > >> if hiding it a bit would be beneficial. The website has been thought
> > as
> > > an
> > > >> enabler/reference and less like a book with a progression ('getting
> > > >> started"s probably) which is more or less what you propose. Wonder
> if
> > we
> > > >> can merge both somehow, probably with the new menu item.
> > > >>
> > > >> I like your menu but it can need a submenu on doc - not sure how
> > mobile
> > > >> handling would be but doable.
> > > >>
> > > >> Maybe we should drop the blog, we never used it accurately.
> > > >>
> > > >>
> > > >> Romain Manni-Bucau
> > > >> @rmannibucau <https://twitter.com/rmannibucau> |  Blog
> > > >> <https://blog-rmannibucau.rhcloud.com> | Old Blog
> > > >> <http://rmannibucau.wordpress.com> | Github <
> > > >> https://github.com/rmannibucau> |
> > > >> LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
> > > >> <https://javaeefactory-rmannibucau.rhcloud.com>
> > > >>
> > > >> 2017-06-26 0:40 GMT+02:00 Thomas Whitmore
> <twhitmore@bravurasolutions.
> > > com
> > > >> >:
> > > >>
> > > >> > Hi Ivan, Romain,
> > > >> >
> > > >> > I probably support having a 'Documentation' item in the top menu.
> > At
> > > >> the
> > > >> > moment there are all the subtopics, but nothing at the top-level
> > says
> > > >> > Documentation!  At a brief glance this is likely to give the
> > > impression
> > > >> > that there isn't documentation, or that it's hard to find.
> > > >> >
> > > >> > From an external perspective 'Documentation', 'Getting Started'
> and
> > > >> > possibly 'Examples' are good top-level headings.
> > > >> >
> > > >> > I would suggest something like:
> > > >> > - Documentation
> > > >> > - Getting Starting
> > > >> > - Examples
> > > >> > - Blog
> > > >> > - Community
> > > >> > - Downloads
> > > >> >
> > > >> > I write quite a lot of documentation so my quick thoughts --
> trying
> > to
> > > >> be
> > > >> > constructive here.
> > > >> >
> > > >> > Reviewing the current 'Developer', 'Admin', 'Advanced' pages --
> > these
> > > >> are
> > > >> > all lacking any overview to tell you the basics and badly empty.
> > > >> > There needs to be some introductory text to start these sections
> and
> > > set
> > > >> > the scene,  TomEE for Developers needs to start with an overview
> of
> > > what
> > > >> > TomEE is & why it's good;  then have some simple guide or guides
> to
> > > >> writing
> > > >> > JEE application, as the first (few) articles. These will show how
> to
> > > use
> > > >> > TomEE's features.
> > > >> >
> > > >> > 'Developer' section should go something like:
> > > >> > - (introductory text)  TomEE is a JEE container. Advantages this
> > > gives.
> > > >> > - JEE Basics  -- basic outlines of how to write a JEE application
> &
> > > link
> > > >> > to other guides
> > > >> > - Eclipse, Intellij Idea, Netbeans: TomEE in and IDE   (maybe:
> but
> > > >> > there's no real content here)
> > > >> > - JEE Feature Guides
> > > >> > - TomEE and Testing
> > > >> >
> > > >> > Perhaps there could be several guides to important JEE areas:
> > > >> > - JEE Guide -- CDI
> > > >> > - JEE Guide -- Datasource
> > > >> > - JEE Guide -- JPA
> > > >> > - JEE Guide -- EJB
> > > >> > - JEE Guide -- CXF & Webservices
> > > >> >
> > > >> > The above topics map well to the areas in Examples
> > > >> > http://tomee.apache.org/examples/index-ng.html which have good
> > > coverage
> > > >> > of examples.. and outlining a little bit of concrete usage should
> > > allow
> > > >> > good opportunities to explain TomEE's configuration, particular
> > > details
> > > >> etc.
> > > >> >
> > > >> > (Little bit of an insight here -- perhaps the fact that we haven't
> > > been
> > > >> > focusing / docing based on the JEE features, has made it hard to
> > write
> > > >> doc?)
> > > >> >
> > > >> > I suggest 'Developer' section should not start with "All you need
> to
> > > >> know
> > > >> > about TomEE classloading". This is not what new developer should
> > need
> > > to
> > > >> > get started with, and is a great way to scare people off.
> > > >> >
> > > >> > Busy these past couple of months, trying to offer some guidance to
> > the
> > > >> > best degree I can but don't have time available to actually do the
> > > >> writing.
> > > >> >
> > > >> >
> > > >> > Regards,
> > > >> > Thomas
> > > >> >
> > > >> > ____________________________________________________________
> > > __________
> > > >> > This email has been scanned by the Symantec Email Security.cloud
> > > >> service.
> > > >> > For more information please visit http://www.symanteccloud.com
> > > >> > ____________________________________________________________
> > > __________
> > > >> >
> > > >>
> > > >
> > > >
> > >
> >
>