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 <[email protected]> wrote: > Le 11 juin 2017 22:25, "Ivan Junckes Filho" <[email protected]> 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 <[email protected] > > > wrote: > > > Hi Ivan > > > > > > 2017-06-11 16:37 GMT+02:00 Ivan Junckes Filho <[email protected]>: > > > > > 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 ;) > > >
