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 ;)
