Re: [Discussion] How to display help informations on the Console
Another choice for #7 would be to include/reuse index tags in the Docs (like #CreateDataSource) which the console could then launch a browser to a Google search of our geronimo.a.o domain, along with including the release tag (GMOxDoc22), so maybe the 2.2 doc search results would be first in the results You'd probably want to write some script/code that could examine the console source and cross-check against the wiki to validate all the expected tags are there. -Donald On 6/16/10 10:49 PM, chi runhua wrote: Thanks for the comments, please find my input inlines. On Mon, Jun 14, 2010 at 10:29 PM, Bill Stoddard wgstodd...@gmail.com mailto:wgstodd...@gmail.com wrote: On 6/14/10 10:01 AM, Donald Woods wrote: #1-3 are good usability improvements. Can we use Dojo for #4-6? Seems hover help would be the best option, as adding an example beside/below every field could require a lot of screen area and doesn't cover the cases for links (like Start/Stop/Restart/Delete). Also, the portlet help page should include the same text as the hoover help (which should be the same resource strings), plus additional help text if needed. Agree~! #7 requires us to stop reorganizing the User Docs and would mean we couldn't rename pages. If we go this route, we should include a hidden comment on each doc page with a reference back to the portlet that has a link to it, so we know not to rename the page unless the portlet link is updated too. Connecting the documentation and console will be expensive to maintain. As a general principle, I would suggest carefully weighing the 'opportunity cost' of adding new features to the server that require on-going maintenance. Each added feature that requires on-going maintenance takes time away from other potentially more important work. Over time as more 'on-going' maintenance requirements accumulate, the development team spends more and more effort to just tending to the maintenance; less time is spent on innovation and keeping current with technology trends. Bill Agree~!. An alternative of #7 is to provide the linkage to doc index page instead of matching the exact page on the top panel of doc. But in the code level, we could define different keys for different portlets for future improvements. All those keys use the same value for each release, for example: For 2.2, use https://cwiki.apache.org/GMOxDOC22/ For 3.0, use https://cwiki.apache.org/GMOxDOC30/ The alternative provides the users a short-cut to Geronimo doc site from console and possibilities to implement #7 for exact match. Jeff
Re: [Discussion] How to display help informations on the Console
Thanks for the comments, please find my input inlines. On Mon, Jun 14, 2010 at 10:29 PM, Bill Stoddard wgstodd...@gmail.comwrote: On 6/14/10 10:01 AM, Donald Woods wrote: #1-3 are good usability improvements. Can we use Dojo for #4-6? Seems hover help would be the best option, as adding an example beside/below every field could require a lot of screen area and doesn't cover the cases for links (like Start/Stop/Restart/Delete). Also, the portlet help page should include the same text as the hoover help (which should be the same resource strings), plus additional help text if needed. Agree~! #7 requires us to stop reorganizing the User Docs and would mean we couldn't rename pages. If we go this route, we should include a hidden comment on each doc page with a reference back to the portlet that has a link to it, so we know not to rename the page unless the portlet link is updated too. Connecting the documentation and console will be expensive to maintain. As a general principle, I would suggest carefully weighing the 'opportunity cost' of adding new features to the server that require on-going maintenance. Each added feature that requires on-going maintenance takes time away from other potentially more important work. Over time as more 'on-going' maintenance requirements accumulate, the development team spends more and more effort to just tending to the maintenance; less time is spent on innovation and keeping current with technology trends. Bill Agree~!. An alternative of #7 is to provide the linkage to doc index page instead of matching the exact page on the top panel of doc. But in the code level, we could define different keys for different portlets for future improvements. All those keys use the same value for each release, for example: For 2.2, use https://cwiki.apache.org/GMOxDOC22/ For 3.0, use https://cwiki.apache.org/GMOxDOC30/ The alternative provides the users a short-cut to Geronimo doc site from console and possibilities to implement #7 for exact match. Jeff
Re: [Discussion] How to display help informations on the Console
#1-3 are good usability improvements. Can we use Dojo for #4-6? Seems hover help would be the best option, as adding an example beside/below every field could require a lot of screen area and doesn't cover the cases for links (like Start/Stop/Restart/Delete). Also, the portlet help page should include the same text as the hoover help (which should be the same resource strings), plus additional help text if needed. #7 requires us to stop reorganizing the User Docs and would mean we couldn't rename pages. If we go this route, we should include a hidden comment on each doc page with a reference back to the portlet that has a link to it, so we know not to rename the page unless the portlet link is updated too. -Donald On 6/13/10 4:53 AM, chi runhua wrote: Hi devs, I noticed that there are 2 different styles to display help information on the Admin Console: a. Using help.jsp when coding and you can only see it after clicking the question mark on the top-right corner of the portlet, meanwhile, you lose the focus but can come back after another click -; for example EJB Server portlet b. Put the help message on the portlet together with those fields, users can refer to the description and input the correct value at the same time, which is more clear and efficient, such as database pool wizard. But if there are lots of fields on the panel, the UI could be a mess and overwhelming. What about we try to unify the style of help infos and improving it in the coming CE 3.0? Here are a few of thoughts for discussion: 1. For the fields requires user selection, they should have a default value ready; 2. Labels must be consistent across the console; 3. For each portlet, we should have a description directly on the top to summarize its major features; 4. For the fields requires user input, an example should be provided right below instead of its detailed description; 5. For checkboxes, we should use hover help to introduce its usage; 6. For the description of each field, use help.jsp when coding, but we should use pop-up panel; 7. Document should be connected with the console more closely, for example, users can refer to document about tasks related to the current portlet instantly instead of googling by themselves. Any comments? Jeff C
Re: [Discussion] How to display help informations on the Console
On 6/14/10 10:01 AM, Donald Woods wrote: #1-3 are good usability improvements. Can we use Dojo for #4-6? Seems hover help would be the best option, as adding an example beside/below every field could require a lot of screen area and doesn't cover the cases for links (like Start/Stop/Restart/Delete). Also, the portlet help page should include the same text as the hoover help (which should be the same resource strings), plus additional help text if needed. #7 requires us to stop reorganizing the User Docs and would mean we couldn't rename pages. If we go this route, we should include a hidden comment on each doc page with a reference back to the portlet that has a link to it, so we know not to rename the page unless the portlet link is updated too. Connecting the documentation and console will be expensive to maintain. As a general principle, I would suggest carefully weighing the 'opportunity cost' of adding new features to the server that require on-going maintenance. Each added feature that requires on-going maintenance takes time away from other potentially more important work. Over time as more 'on-going' maintenance requirements accumulate, the development team spends more and more effort to just tending to the maintenance; less time is spent on innovation and keeping current with technology trends. Bill
[Discussion] How to display help informations on the Console
Hi devs, I noticed that there are 2 different styles to display help information on the Admin Console: a. Using help.jsp when coding and you can only see it after clicking the question mark on the top-right corner of the portlet, meanwhile, you lose the focus but can come back after another click -; for example EJB Server portlet b. Put the help message on the portlet together with those fields, users can refer to the description and input the correct value at the same time, which is more clear and efficient, such as database pool wizard. But if there are lots of fields on the panel, the UI could be a mess and overwhelming. What about we try to unify the style of help infos and improving it in the coming CE 3.0? Here are a few of thoughts for discussion: 1. For the fields requires user selection, they should have a default value ready; 2. Labels must be consistent across the console; 3. For each portlet, we should have a description directly on the top to summarize its major features; 4. For the fields requires user input, an example should be provided right below instead of its detailed description; 5. For checkboxes, we should use hover help to introduce its usage; 6. For the description of each field, use help.jsp when coding, but we should use pop-up panel; 7. Document should be connected with the console more closely, for example, users can refer to document about tasks related to the current portlet instantly instead of googling by themselves. Any comments? Jeff C
