Multilingual central based 1.5 helpserver
3 views
Skip to first unread message
Ole Ottosen
Aug 2, 2009, 12:37:29 PM8/2/09
to joomla-wg-production
Hi folks,
Today in the Translation Coordination Team we discussed how to help making it easier for our +50 Translation Teams to provide localised help.
Current solution of populating an older 1.0 dump to a temporary 1.0 site, then migrate to new clean 1.5 site, for to finally translate, is just not optimal.
Means that too few languages currently are providing localised help, which is a pity really.
Looks like we actually have the manpower available to make this change to the better, so we decided to create a subgroup 'International Help sites', with the purpose of creating a multilingual joomla! 1.5 based central help resource.
The technical part of having urls to work correctly etc, the group will have to deal with and solve.
For this to happen we will need a little help to get started:
1. An up-to-date dump, reflecting the newest content of help.j / docs.../Help_screens, ready to use in a new 1.5 site hosted a joomla.org.
2. New subdomain at joomla.org (will check with Brad)
3. Joom!Fish with some extra features (will check up with Alex)
So basically its a new dump we need from Documentation. Can this be provided? Thanks.
Ole
Chris Davenport
Aug 2, 2009, 4:33:01 PM8/2/09
to joomla-wg-...@googlegroups.com
Hi Ole,
Actually, I've been thinking about this quite a bit these last few days as the first 1.6 beta release is frighteningly close and we still haven't managed to get the help system rewritten. Now, I was going to put out a call for assistance but then it occurred to me that maybe there is a different, although not necessarily better, way of doing things, and I've been thinking about what the consequences would be. So your thoughts are very timely.
The way we currently do help screens is very unsatisfactory. Having moved the documentation over to the wiki but leaving the help screens on help.joomla.org we find ourselves stuck with a process that is slow, labour-intensive and somewhat error-prone. It was in the spirit of trying to find a better solution that I proposed the white paper (http://forum.joomla.org/viewtopic.php?f=502&t=268156) which recommends a new help system that is able to take help pages hosted just about anywhere, with the objective being to host the official Joomla help pages on the documentation wiki itself and so eliminate the problematical copy-pasting onto the old help site (which, as you've noted, is still running Joomla 1.0.x).
However, the white paper proposal suffers from a number of drawbacks:
1. It requires significant developer time. Marieke made a valiant effort to implement it, but ran out of time. I'd love to write it myself, but I am equally time-constrained at the moment.
2. It is a 1.6 onwards solution and leaves 1.5 users still working with the old help system.
3. It suffers from the same "template problem" that the existing help system suffers from. At present, the help screens look good provided you don't click on any links that they contain. If you do then you will be taken to a "regular" Joomla page on the help site, complete with menus, headers and footers, and so on. The help screens look and work best when they are not surrounded by the paraphernalia of menus and other distractions that come with the default template. Hosting the help pages on the wiki doesn't solve this problem either.
So, here's what I've been thinking about...
Firstly, we should definitely host the help screens on the wiki. It is much, much easier to create and maintain them there, and they can be amended and improved by anyone, so there are no barriers to participation and no delay in getting updated screens out to users.
However, rather than create a new help system that can cope with a non-Joomla help server, we instead write a Joomla component that can proxy the help screens from the wiki. By installing that component on a Joomla 1.5 instance with a default template that is purely aimed at delivering help screens, we immediately solve the "template problem". It would require only trivial changes to the code in 1.6 and those same changes could be applied to 1.5 so both versions could be supported in the same way. Perhaps best of all, the component should be pretty simple to write and could be written, tested, deployed and maintained more or less independently of the Joomla release cycle. The only downside that I can see, so far, is that it is nowhere near as flexible.
This is how it would work....
Admin user clicks on the help toolbar icon (or whatever that morphs into in 1.6). Joomla opens a popup window and passes a URL to it (this is the only part that would need changing: the structure of the URL would need to be different). The request would presently go to help.joomla.org, but we change it so it points to a new, dedicated help server instead. The help server loads the new component which parses the request and makes a request to the wiki using the MediaWiki web API. The response from the wiki is then parsed for links and the links modified on-the-fly to point to the new help server instead of the wiki. The resulting page is then rendered into the user's popup window.
As for multi-lingual help, I can't see any reason why this can't be extended to cope with any number of languages. If we're hosting the help screens ourselves then the proxy component can easily cope with the URL transformations that would be needed. For help screens hosted elsewhere we would make the component available to whoever wants to use it (GPL-licensed, of course), so they could run the same kind of configuration.
What still needs to be thought about are things like how to handle the Help -> Joomla Help screen (if indeed we should) and how to handle third-party component help. I'm sure they can be handled appropriately, but I haven't thought it through enough yet.
Anyway, I have a holiday coming up, from 10th August for a week and I've been thinking of working on writing the component then. I don't think it would take long, but until I actually try it I won't know what the problems are.
What do you think?
Chris.
Actually, I've been thinking about this quite a bit these last few days as the first 1.6 beta release is frighteningly close and we still haven't managed to get the help system rewritten. Now, I was going to put out a call for assistance but then it occurred to me that maybe there is a different, although not necessarily better, way of doing things, and I've been thinking about what the consequences would be. So your thoughts are very timely.
The way we currently do help screens is very unsatisfactory. Having moved the documentation over to the wiki but leaving the help screens on help.joomla.org we find ourselves stuck with a process that is slow, labour-intensive and somewhat error-prone. It was in the spirit of trying to find a better solution that I proposed the white paper (http://forum.joomla.org/viewtopic.php?f=502&t=268156) which recommends a new help system that is able to take help pages hosted just about anywhere, with the objective being to host the official Joomla help pages on the documentation wiki itself and so eliminate the problematical copy-pasting onto the old help site (which, as you've noted, is still running Joomla 1.0.x).
However, the white paper proposal suffers from a number of drawbacks:
1. It requires significant developer time. Marieke made a valiant effort to implement it, but ran out of time. I'd love to write it myself, but I am equally time-constrained at the moment.
2. It is a 1.6 onwards solution and leaves 1.5 users still working with the old help system.
3. It suffers from the same "template problem" that the existing help system suffers from. At present, the help screens look good provided you don't click on any links that they contain. If you do then you will be taken to a "regular" Joomla page on the help site, complete with menus, headers and footers, and so on. The help screens look and work best when they are not surrounded by the paraphernalia of menus and other distractions that come with the default template. Hosting the help pages on the wiki doesn't solve this problem either.
So, here's what I've been thinking about...
Firstly, we should definitely host the help screens on the wiki. It is much, much easier to create and maintain them there, and they can be amended and improved by anyone, so there are no barriers to participation and no delay in getting updated screens out to users.
However, rather than create a new help system that can cope with a non-Joomla help server, we instead write a Joomla component that can proxy the help screens from the wiki. By installing that component on a Joomla 1.5 instance with a default template that is purely aimed at delivering help screens, we immediately solve the "template problem". It would require only trivial changes to the code in 1.6 and those same changes could be applied to 1.5 so both versions could be supported in the same way. Perhaps best of all, the component should be pretty simple to write and could be written, tested, deployed and maintained more or less independently of the Joomla release cycle. The only downside that I can see, so far, is that it is nowhere near as flexible.
This is how it would work....
Admin user clicks on the help toolbar icon (or whatever that morphs into in 1.6). Joomla opens a popup window and passes a URL to it (this is the only part that would need changing: the structure of the URL would need to be different). The request would presently go to help.joomla.org, but we change it so it points to a new, dedicated help server instead. The help server loads the new component which parses the request and makes a request to the wiki using the MediaWiki web API. The response from the wiki is then parsed for links and the links modified on-the-fly to point to the new help server instead of the wiki. The resulting page is then rendered into the user's popup window.
As for multi-lingual help, I can't see any reason why this can't be extended to cope with any number of languages. If we're hosting the help screens ourselves then the proxy component can easily cope with the URL transformations that would be needed. For help screens hosted elsewhere we would make the component available to whoever wants to use it (GPL-licensed, of course), so they could run the same kind of configuration.
What still needs to be thought about are things like how to handle the Help -> Joomla Help screen (if indeed we should) and how to handle third-party component help. I'm sure they can be handled appropriately, but I haven't thought it through enough yet.
Anyway, I have a holiday coming up, from 10th August for a week and I've been thinking of working on writing the component then. I don't think it would take long, but until I actually try it I won't know what the problems are.
What do you think?
Chris.
2009/8/2 Ole Ottosen <ole.o...@joomla.org>
Ole Ottosen
Aug 2, 2009, 6:08:15 PM8/2/09
to joomla-wg-...@googlegroups.com
Good feedback. Thanks Chris.
Will have a closer look at your input, and then decide what I think :)
Ole
Chris Davenport
Aug 15, 2009, 1:48:04 PM8/15/09
to joomla-wg-...@googlegroups.com
Just got back from holiday where I was able to code the proxy help component and a patch for 1.5 to be able to use it. Details here: http://forum.joomla.org/viewtopic.php?f=199&t=430887
It pretty much solves the immediate problems we have had with the 1.5 (and 1.6) help screens for the English wiki and it can be very easily rolled out to the translation teams.
It pretty much solves the immediate problems we have had with the 1.5 (and 1.6) help screens for the English wiki and it can be very easily rolled out to the translation teams.
Ole Ottosen
Aug 15, 2009, 2:08:04 PM8/15/09
to joomla-wg-...@googlegroups.com
The description sounds promising.
Will go give it a test drive, to see what your relaxing holiday has resulted in.
Thanks for your effort Chris!
Ole
Reply all
Reply to author
Forward
0 new messages