[xwiki-devs] [Proposal] Add fields to administration app whose names are links to explanations of those fields on xwiki.org
The problem: When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for. eg: Boolean field named: "Check Active fields for user authentication" To a new administrator, this is confusing and it's not apparent where to look for an explanation. Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on. This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags. WDYT? Caleb
Hi Caleb, On Feb 11, 2010, at 3:43 AM, Caleb James DeLisle wrote:
The problem: When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for. eg: Boolean field named: "Check Active fields for user authentication"
To a new administrator, this is confusing and it's not apparent where to look for an explanation.
Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on.
This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags.
WDYT?
I don't like it too much. IMO XE should be standalone. This is why we've taken pains to have the syntax guide directly in XE for example. The reason is simple: you can install XE locally and have no internet access. We do have a solution for field help. I haven't used it myself but I'm sure others here can comment on it. It's used for example on the XWiki SAS intranet, something like this: http://tinycoke.com/_6rXVfMRfwk2/screen_shot_2010-02-11_at_8.39.20_am.png WDYT? Thanks -Vincent
Vincent Massol wrote:
Hi Caleb,
On Feb 11, 2010, at 3:43 AM, Caleb James DeLisle wrote:
The problem: When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for. eg: Boolean field named: "Check Active fields for user authentication"
To a new administrator, this is confusing and it's not apparent where to look for an explanation.
Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on.
This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags.
WDYT?
I don't like it too much. IMO XE should be standalone. This is why we've taken pains to have the syntax guide directly in XE for example. The reason is simple: you can install XE locally and have no internet access.
We do have a solution for field help. I haven't used it myself but I'm sure others here can comment on it.
It's used for example on the XWiki SAS intranet, something like this: http://tinycoke.com/_6rXVfMRfwk2/screen_shot_2010-02-11_at_8.39.20_am.png
WDYT?
Though I agree with the philosophy of separating XE from xwiki.org, my opinion is that the advantages of xwiki.org being more likely to be up to date and not having to maintain multiple copies of each help document (and svn commit them) outweigh the disadvantage of system administrators who can't access the internet being unable to see the help files. An alternative might be to have maven pull the documents from xwiki.org and put them in XE automatically, but I still don't like the fact that users will be forced to install documentation in their database to have the "default pages" perhaps the most elegant solution is to provide xwiki.org for download as an xar so users can have all of the documentation if they wish, links could point to an application which would redirect the user to xwiki.org if the documentation was not locally installed. More realistically, I think documentation will just remain harder to find. Anyway that is my opinion, Caleb
Thanks -Vincent _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
On Feb 11, 2010, at 10:20 AM, Caleb James DeLisle wrote:
Vincent Massol wrote:
Hi Caleb,
On Feb 11, 2010, at 3:43 AM, Caleb James DeLisle wrote:
The problem: When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for. eg: Boolean field named: "Check Active fields for user authentication"
To a new administrator, this is confusing and it's not apparent where to look for an explanation.
Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on.
This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags.
WDYT?
I don't like it too much. IMO XE should be standalone. This is why we've taken pains to have the syntax guide directly in XE for example. The reason is simple: you can install XE locally and have no internet access.
We do have a solution for field help. I haven't used it myself but I'm sure others here can comment on it.
It's used for example on the XWiki SAS intranet, something like this: http://tinycoke.com/_6rXVfMRfwk2/screen_shot_2010-02-11_at_8.39.20_am.png
WDYT?
Though I agree with the philosophy of separating XE from xwiki.org, my opinion is that the advantages of xwiki.org being more likely to be up to date and not having to maintain multiple copies of each help document (and svn commit them) outweigh the disadvantage of system administrators who can't access the internet being unable to see the help files.
An alternative might be to have maven pull the documents from xwiki.org and put them in XE automatically, but I still don't like the fact that users will be forced to install documentation in their database to have the "default pages"
I've done it the other way around for the syntax page. It's pulled from svn on xwiki.org.
perhaps the most elegant solution is to provide xwiki.org for download as an xar so users can have all of the documentation if they wish, links could point to an application which would redirect the user to xwiki.org if the documentation was not locally installed.
Yes, but not in this manner IMO. We need it controlled (versioned, committed, with svn tag, ip clearance, etc). What I'd propose is to create a help application in platform/applications (but not for your use case, more for tutorials, getting started guide, etc - We'd need to define the content) and have this help app available on xwiki.org too (in order to prevent duplication). FYI here's how I've done it for the syntax page (but this would need to be improved for a full XAR): {{velocity}} #set ($content = $xwiki.getURLContent("http://svn.xwiki.org/svnroot/xwiki/enterprise/trunk/wiki/src/main/resources/...")) #set ($newdoc = $xwiki.getDocument("Dummy")) #set ($newdocprivate = $newdoc.getDocument()) $newdocprivate.fromXML($content) {{html clean="false"}} $newdoc.getRenderedContent() {{/html}} {{/velocity}} IMO for your use case what the user needs is a tooltip or a popup that explains what a field is. What he doesn't want is a new page opened or pointing to a help page where he has to parse the page to look for the information he need.
More realistically, I think documentation will just remain harder to find.
I don't understand this point. Could you explain? Thanks -Vincent
Anyway that is my opinion,
Caleb
Thanks -Vincent _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
Vincent Massol wrote:
On Feb 11, 2010, at 10:20 AM, Caleb James DeLisle wrote:
Vincent Massol wrote:
Hi Caleb,
On Feb 11, 2010, at 3:43 AM, Caleb James DeLisle wrote:
The problem: When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for. eg: Boolean field named: "Check Active fields for user authentication"
To a new administrator, this is confusing and it's not apparent where to look for an explanation.
Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on.
This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags.
WDYT? I don't like it too much. IMO XE should be standalone. This is why we've taken pains to have the syntax guide directly in XE for example. The reason is simple: you can install XE locally and have no internet access.
We do have a solution for field help. I haven't used it myself but I'm sure others here can comment on it.
It's used for example on the XWiki SAS intranet, something like this: http://tinycoke.com/_6rXVfMRfwk2/screen_shot_2010-02-11_at_8.39.20_am.png
WDYT? Though I agree with the philosophy of separating XE from xwiki.org, my opinion is that the advantages of xwiki.org being more likely to be up to date and not having to maintain multiple copies of each help document (and svn commit them) outweigh the disadvantage of system administrators who can't access the internet being unable to see the help files.
An alternative might be to have maven pull the documents from xwiki.org and put them in XE automatically, but I still don't like the fact that users will be forced to install documentation in their database to have the "default pages"
I've done it the other way around for the syntax page. It's pulled from svn on xwiki.org.
perhaps the most elegant solution is to provide xwiki.org for download as an xar so users can have all of the documentation if they wish, links could point to an application which would redirect the user to xwiki.org if the documentation was not locally installed.
Yes, but not in this manner IMO. We need it controlled (versioned, committed, with svn tag, ip clearance, etc). What I'd propose is to create a help application in platform/applications (but not for your use case, more for tutorials, getting started guide, etc - We'd need to define the content) and have this help app available on xwiki.org too (in order to prevent duplication).
FYI here's how I've done it for the syntax page (but this would need to be improved for a full XAR):
{{velocity}} #set ($content = $xwiki.getURLContent("http://svn.xwiki.org/svnroot/xwiki/enterprise/trunk/wiki/src/main/resources/...")) #set ($newdoc = $xwiki.getDocument("Dummy")) #set ($newdocprivate = $newdoc.getDocument()) $newdocprivate.fromXML($content) {{html clean="false"}} $newdoc.getRenderedContent() {{/html}} {{/velocity}}
IMO for your use case what the user needs is a tooltip or a popup that explains what a field is. What he doesn't want is a new page opened or pointing to a help page where he has to parse the page to look for the information he need.
My current design uses links which could point to javascript:function(); The only change would be to make the admin page use skin extensions of the included pages so the javascript function (open popup) could be defined.
More realistically, I think documentation will just remain harder to find.
I don't understand this point. Could you explain?
On the one hand I was trying to say that if there isn't an established system for connecting the application interface to it's documentation then developers will document less and make less of an effort to make it easily accessible from the app. On the other hand I was just whining that it would make my job harder. Caleb
Thanks -Vincent
Anyway that is my opinion,
Caleb
Thanks -Vincent _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
Hi Caleb, Caleb James DeLisle wrote:
The problem:
When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for.
Then maybe the right solution is to add a description. The fact that class properties don't have a description but only a name and a pretty name looks like a serious limitation to me. What would take to add a description field to a class property? Hope this helps, Marius
eg: Boolean field named: "Check Active fields for user authentication"
To a new administrator, this is confusing and it's not apparent where to look for an explanation.
Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on.
This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags.
WDYT?
Caleb
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
There was something to address this before the class editor overhaul, there was a tooltip field. It's never been used in our default distrib, may be we should get it back and improve it. See http://platform.xwiki.org/xwiki/bin/view/DevGuide/Creating+a+form+with+valid... JV. On Thu, Feb 11, 2010 at 12:09 PM, Marius Dumitru Florea <mariusdumitru.florea@xwiki.com> wrote:
Hi Caleb,
Caleb James DeLisle wrote:
The problem:
When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for.
Then maybe the right solution is to add a description. The fact that class properties don't have a description but only a name and a pretty name looks like a serious limitation to me. What would take to add a description field to a class property?
Hope this helps, Marius
eg: Boolean field named: "Check Active fields for user authentication"
To a new administrator, this is confusing and it's not apparent where to look for an explanation.
Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on.
This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags.
WDYT?
Caleb
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
Jean-Vincent Drean wrote:
There was something to address this before the class editor overhaul, there was a tooltip field.
It's never been used in our default distrib, may be we should get it back and improve it.
+1 Thanks, Marius
See http://platform.xwiki.org/xwiki/bin/view/DevGuide/Creating+a+form+with+valid...
JV.
On Thu, Feb 11, 2010 at 12:09 PM, Marius Dumitru Florea <mariusdumitru.florea@xwiki.com> wrote:
Hi Caleb,
Caleb James DeLisle wrote:
The problem: When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for. Then maybe the right solution is to add a description. The fact that class properties don't have a description but only a name and a pretty name looks like a serious limitation to me. What would take to add a description field to a class property?
Hope this helps, Marius
eg: Boolean field named: "Check Active fields for user authentication"
To a new administrator, this is confusing and it's not apparent where to look for an explanation.
Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on.
This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags.
WDYT?
Caleb
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
On 02/11/2010 03:43 AM, Caleb James DeLisle wrote:
The problem: When a new wiki administrator uses the registration application, they are faced with a set of fields with names which are too short to explain what each field is for. eg: Boolean field named: "Check Active fields for user authentication"
To a new administrator, this is confusing and it's not apparent where to look for an explanation.
Proposal: I would like to add fields with names which are links to descriptions of what those fields are for. I can implement this in the "configurable" class which I am working on.
This means XE would have links to xwiki.org but it already does on the dashboard explanation of tags.
WDYT?
I also believe that this is not a good idea. The wiki should be self-documented, any interface element should be clear. If a simple name is not good enough, then a tooltip should provide more information. If that's still not enough, then there is a Documentation link (to xwiki.org) at the bottom of the page already, the user should find the full documentation starting from there. But this is just the ideal solution. In reality, there are plenty of places where the short name is not descriptive enough (for example this check Active field), tooltips are rarely used, and many users complain that they can't find what they're looking for on xwiki.org. All these must be improved. For a start, this field could be renamed to "Require account validation through email" or something similar. Is that still not suggestive enough? Then, we need to make the property tooltip work. Third, we need to reorganize xwiki.org. -- Sergiu Dumitriu http://purl.org/net/sergiu/
participants (5)
-
Caleb James DeLisle -
Jean-Vincent Drean -
Marius Dumitru Florea -
Sergiu Dumitriu -
Vincent Massol