11 Feb
2010
11 Feb
'10
11:34 a.m.
Vincent Massol wrote:
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
On Feb 11, 2010, at 10:20 AM, Caleb James DeLisle
wrote:
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.
Vincent Massol wrote:
I've done it the other way around for the syntax page. It's pulled from svn on
xwiki.org.
Hi Caleb,
On Feb 11, 2010, at 3:43 AM, Caleb James DeLisle wrote:
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" 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? 
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/XWiki/XWikiSyntax.xml"))
#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
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
Thanks
-Vincent
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs