You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geronimo.apache.org by chi runhua <ch...@gmail.com> on 2010/06/13 10:53:53 UTC
[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
Re: [Discussion] How to display help informations on the Console
Posted by Donald Woods <dw...@apache.org>.
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 <wgstoddard@gmail.com
> <ma...@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
Posted by chi runhua <ch...@gmail.com>.
Thanks for the comments, please find my input inlines.
On Mon, Jun 14, 2010 at 10:29 PM, Bill Stoddard <wg...@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
Posted by Bill Stoddard <wg...@gmail.com>.
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
Re: [Discussion] How to display help informations on the Console
Posted by Donald Woods <dw...@apache.org>.
#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
Posted by David Jencks <da...@yahoo.com>.
On Jun 13, 2010, at 1: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?
These all look like great ideas to me!
thanks
david jencks
>
> Jeff C