In an effort to provide a framework to get decent documentation into Views 2, I determined that the built in Drupal help is simply not satisfactory for my needs. So I built this framework as a generic module that any module can utilize as an option to get expanded documentation about the administrative side of a module. Currently the module is in beta status -- it is almost certainly missing features, but it has what I want. I'll happily, however, let others who want to expand this to meet the needs of other modules. In my ideal world, this module will be improved, code-wise, until it is core worthy and the basic "how to use Drupal" documentation ends up shipped with Drupal. Perhaps this can happen as part of an upcoming Summer of Code project; in any case, I put this out there for people to use and see what we can do with it. Also, look at it this way: If Views uses it, you know that 50% of the modules out there for Drupal 6 will at least be exposed to it. Oh, the module is for Drupal 6 but can probably be backported to D5 with not a lot of effort. If someone wants to do that, great. I won't be doing it, though. =)
Earl Miles wrote:
In an effort to provide a framework to get decent documentation into Views 2, I determined that the built in Drupal help is simply not satisfactory for my needs. So I built this framework as a generic module that any module can utilize as an option to get expanded documentation about the administrative side of a module.
Currently the module is in beta status -- it is almost certainly missing features, but it has what I want. I'll happily, however, let others who want to expand this to meet the needs of other modules. In my ideal world, this module will be improved, code-wise, until it is core worthy and the basic "how to use Drupal" documentation ends up shipped with Drupal. Perhaps this can happen as part of an upcoming Summer of Code project; in any case, I put this out there for people to use and see what we can do with it.
Also, look at it this way: If Views uses it, you know that 50% of the modules out there for Drupal 6 will at least be exposed to it.
Oh, the module is for Drupal 6 but can probably be backported to D5 with not a lot of effort. If someone wants to do that, great. I won't be doing it, though. =) By the way, I'm keenly interested in the opinion of the translation wizards out there to make sure I got it right and am not missing something necessary or that could make this even easier.
The module is located at http://drupal.org/project/advanced_help. Konstantin Käfer -- http://kkaefer.com/ On 19.04.2008, at 03:25, Earl Miles wrote:
Earl Miles wrote:
In an effort to provide a framework to get decent documentation into Views 2, I determined that the built in Drupal help is simply not satisfactory for my needs. So I built this framework as a generic module that any module can utilize as an option to get expanded documentation about the administrative side of a module.
Currently the module is in beta status -- it is almost certainly missing features, but it has what I want. I'll happily, however, let others who want to expand this to meet the needs of other modules. In my ideal world, this module will be improved, code- wise, until it is core worthy and the basic "how to use Drupal" documentation ends up shipped with Drupal. Perhaps this can happen as part of an upcoming Summer of Code project; in any case, I put this out there for people to use and see what we can do with it.
Also, look at it this way: If Views uses it, you know that 50% of the modules out there for Drupal 6 will at least be exposed to it.
Oh, the module is for Drupal 6 but can probably be backported to D5 with not a lot of effort. If someone wants to do that, great. I won't be doing it, though. =) By the way, I'm keenly interested in the opinion of the translation wizards out there to make sure I got it right and am not missing something necessary or that could make this even easier.
Any ideas how this will intersect with the accepted Summer of Code project: Revamp Drupal's help system (Gurpartap Singh), mentored by dmitrig01 and heyrocker. -- Ken Rickard agentrickard@gmail.com http://ken.therickards.com On Sat, Apr 19, 2008 at 4:57 AM, Konstantin Käfer <kkaefer@gmail.com> wrote:
The module is located at http://drupal.org/project/advanced_help.
Konstantin Käfer -- http://kkaefer.com/
On 19.04.2008, at 03:25, Earl Miles wrote:
Earl Miles wrote:
In an effort to provide a framework to get decent documentation into Views 2, I determined that the built in Drupal help is simply not satisfactory for my needs. So I built this framework as a generic module that any module can utilize as an option to get expanded documentation about the administrative side of a module.
Currently the module is in beta status -- it is almost certainly missing features, but it has what I want. I'll happily, however, let others who want to expand this to meet the needs of other modules. In my ideal world, this module will be improved, code-wise, until it is core worthy and the basic "how to use Drupal" documentation ends up shipped with Drupal. Perhaps this can happen as part of an upcoming Summer of Code project; in any case, I put this out there for people to use and see what we can do with it.
Also, look at it this way: If Views uses it, you know that 50% of the modules out there for Drupal 6 will at least be exposed to it.
Oh, the module is for Drupal 6 but can probably be backported to D5 with not a lot of effort. If someone wants to do that, great. I won't be doing it, though. =)
By the way, I'm keenly interested in the opinion of the translation wizards out there to make sure I got it right and am not missing something necessary or that could make this even easier.
Ken Rickard wrote:
Any ideas how this will intersect with the accepted Summer of Code project:
Revamp Drupal's help system (Gurpartap Singh), mentored by dmitrig01 and heyrocker.
Both of them have already taken a look at this module. While I do not know what they will do with it, I've offered it up to Gurpartap in any way he needs, including making him a maintainer so that he can expand it to suit his purposes. I'm not sure what the end result will be; my hope is that it will mean more of his work will be on organization and placement of help than it will be on creating new technology for help, but there are a number of ideas on his list that this module doesn't do. (A centralized help server, for one). Though there are some theoretical problems with that idea that concern me.
Hey Earl, I've given a try to the module and it looks great. I also agree the built in search is not that good -it's ok for small texts though- and we do need something better, specially if we want to produce better and bigger help pages. About the translation part, it has some small bug so not really working yet (I'll be posting a patch), but doesn't look bad. However I wish we were able to have some multilanguage system like this that didn't always rely on the primary version in English. I mean it's not always English + other languages. I.e. I may have a module built for a site with some help pages only in Spanish, that I may not need in English at first. Then maybe I want to contribute the module later for which I'd create the English translation, or I may add an English version to my site... but it would be nice to be able to have the pages in the right place from the beginning. I'm thinking it would be great have a drupal_language_include() that checked for the right language file with some fallbacks but didn't need always the English version first. Anyway, this new help system is certainly an improvement over the current one, as documentation on static pages is much easier to maintain and translate than the handful of spare strings we currently have to deal with and also it doesn't need a php developer just to fix some string. Other ideas (for the wish list for now, I hope I'll be able to send some patches), may be to use xml files or some simpler markup for the text files, just to keep the texts cleaner and easier to maintain and translate. Also the current directory structure makes it difficult to share static files (css, images, etc..) between translations, I guess that could be fixed with some parsing of the source text files and maybe using some identifiers instead of real urls for links and images.... And there's the internal site links that may need some parsing too to point at the right pages. Nice job, I think I'll be the first user of this new system :-) Jose Earl Miles wrote:
Earl Miles wrote:
In an effort to provide a framework to get decent documentation into Views 2, I determined that the built in Drupal help is simply not satisfactory for my needs. So I built this framework as a generic module that any module can utilize as an option to get expanded documentation about the administrative side of a module.
Currently the module is in beta status -- it is almost certainly missing features, but it has what I want. I'll happily, however, let others who want to expand this to meet the needs of other modules. In my ideal world, this module will be improved, code-wise, until it is core worthy and the basic "how to use Drupal" documentation ends up shipped with Drupal. Perhaps this can happen as part of an upcoming Summer of Code project; in any case, I put this out there for people to use and see what we can do with it.
Also, look at it this way: If Views uses it, you know that 50% of the modules out there for Drupal 6 will at least be exposed to it.
Oh, the module is for Drupal 6 but can probably be backported to D5 with not a lot of effort. If someone wants to do that, great. I won't be doing it, though. =) By the way, I'm keenly interested in the opinion of the translation wizards out there to make sure I got it right and am not missing something necessary or that could make this even easier.
Jose A. Reyero wrote:
I also agree the built in search is not that good -it's ok for small texts though- and we do need something better, specially if we want to produce better and bigger help pages.
I think the built in search should be fine for help text searching. We can probably improve it a bit with keyword weighting (I put an issue into the queue about this).
However I wish we were able to have some multilanguage system like this that didn't always rely on the primary version in English. I mean it's not always English + other languages. I.e. I may have a module built for a site with some help pages only in Spanish, that I may not need in English at first. Then maybe I want to contribute the module later for which I'd create the English translation, or I may add an English version to my site... but it would be nice to be able to have the pages in the right place from the beginning.
Interestingly, the way this system works, you could put the base help in any language. It'd still look in 'en' as that's the default language, and if there's a translation there it would use that. That said, I wouldn't want the rest of Drupal to have modules in other languages; having a single base language means that sites with that language don't need to turn on the localization features, which adds extra database work.
Anyway, this new help system is certainly an improvement over the current one, as documentation on static pages is much easier to maintain and translate than the handful of spare strings we currently have to deal with and also it doesn't need a php developer just to fix some string.
That's definitely one of the goals.
Other ideas (for the wish list for now, I hope I'll be able to send some patches), may be to use xml files or some simpler markup for the text files, just to keep the texts cleaner and easier to maintain and translate. Also the current directory structure makes it difficult to share static files (css, images, etc..) between translations, I guess that could be fixed with some parsing of the source text files and maybe using some identifiers instead of real urls for links and images.... And there's the internal site links that may need some parsing too to point at the right pages.
Right now there's some parsing for href=" and src=" to help with that; but it's not checking for translation, so there might need to be a little extra work there. Some images may not need to be translated, whereas some others might be. But adding a few more keywords (transpath: vs path: maybe?) could ease that. Thanks for the review!
On Sun, Apr 20, 2008 at 11:29 PM, Earl Miles <merlin@logrus.com> wrote:
However I wish we were able to have some multilanguage system like this that didn't always rely on the primary version in English. I mean it's not always English + other languages. I.e. I may have a module built for a site with some help pages only in Spanish, that I may not need in English at first. Then maybe I want to contribute the module later for which I'd create the English translation, or I may add an English version to my site... but it would be nice to be able to have the pages in the right place from the beginning.
Interestingly, the way this system works, you could put the base help in any language. It'd still look in 'en' as that's the default language, and if there's a translation there it would use that.
That said, I wouldn't want the rest of Drupal to have modules in other languages; having a single base language means that sites with that language don't need to turn on the localization features, which adds extra database work.
Well, I think Jose refers to those developers "out there", who might develop custom modules for local (non-English sites), and might not want / be able to write English help pages. Hacking in empty base files for English might not be a good option. Gabor
Well, I think Jose refers to those developers "out there", who might develop custom modules for local (non-English sites), and might not want / be able to write English help pages. Hacking in empty base files for English might not be a good option.
Gabor
Isn't this an edge-case? Even if my primary language is German, I will write the module documentation in English first. By doing that module developers ensure that a module (including its documentation) is actually usable for all Drupal users, speaking all kind of different languages. Also, by doing that I often determine phrases that may be hard to translate into other languages, including German. Daniel
On Mon, Apr 21, 2008 at 10:23 AM, Daniel F. Kudwien <news@unleashedmind.com> wrote:
Well, I think Jose refers to those developers "out there", who might develop custom modules for local (non-English sites), and might not want / be able to write English help pages. Hacking in empty base files for English might not be a good option.
Gabor
Isn't this an edge-case? Even if my primary language is German, I will write the module documentation in English first. By doing that module developers ensure that a module (including its documentation) is actually usable for all Drupal users, speaking all kind of different languages. Also, by doing that I often determine phrases that may be hard to translate into other languages, including German.
Well, I did write some modules in Hungarian only (ie. drupal.hu's site showcase gallery module). This did not let me to share the module straight away with the Dutch/Belgian Drupal community site builders, who requested it (although they took it in Hungarian anyway, and we will see how usable it is for them that way). Anyway, it is all to easy to be short-sighted with languages, it could easily be that the developer writing the module would write horrible English, and you are better off not requiring that as a non-English Drupal shop. It admittedly also cuts costs. Think of internal development for clients not development for the community. Admit it or not, lots of people don't participate in the community, but just take what they can get (and then others tend to be lazy as my example shows). Gabor
Daniel F. Kudwien wrote:
Well, I think Jose refers to those developers "out there", who might develop custom modules for local (non-English sites), and might not want / be able to write English help pages. Hacking in empty base files for English might not be a good option.
Gabor
Isn't this an edge-case? Even if my primary language is German, I will write the module documentation in English first. By doing that module developers ensure that a module (including its documentation) is actually usable for all Drupal users, speaking all kind of different languages. Also, by doing that I often determine phrases that may be hard to translate into other languages, including German.
Daniel
There are modules and modules, and clients and clients you may work for. Some modules are just too site specific to be contributed, though the site may need later an English translation (or not). And when developing a custom module for a client, even if you are allowed to contribute it later, I don't think it's ok to charge the client for the time to write an English documentation page (plus changes, fixes and retranslations) they don't need at all. Unless of course the work is meant to be contributed from the start so you write English docs first. That said, it's not my case anymore as I work now most of the time for the 'English speaking world' :-), and most of the time the question is more 'how can we make this generic enough to be contributable', but the other case is not that rare. Many modules are born because of very specific website or people's needs and may end up in contrib or not, not because we developers don't want to, but sometimes it just doesn't make sense. So just lets make easier it to happen. Jose
Gábor Hojtsy wrote:
Well, I think Jose refers to those developers "out there", who might develop custom modules for local (non-English sites), and might not want / be able to write English help pages. Hacking in empty base files for English might not be a good option.
This is fine for help files. And the system work will that way beautifully with help files, so I'm more than happy to tell module developers to write their help files in whatever base language they want. If English users use it, I'm sure an English translation would be easy enough to get and put in.
Earl Miles wrote:
Gábor Hojtsy wrote:
Well, I think Jose refers to those developers "out there", who might develop custom modules for local (non-English sites), and might not want / be able to write English help pages. Hacking in empty base files for English might not be a good option. Yes, thanks Gabor, that's exactly what I'm talking about.
This is fine for help files. And the system work will that way beautifully with help files, so I'm more than happy to tell module developers to write their help files in whatever base language they want. If English users use it, I'm sure an English translation would be easy enough to get and put in.
This sounds great. Usually when developing a module for a client in a different language, I try to use t() wrapped English strings when there's just a few of them, always thinking that it may-be contributed/translated in the future. The main issue though were the help texts which are usually longer, so it was not practical at all to use the localization system for that. But if this new system allows any base language -I had missed that when looking at the code- then it is just great. Thanks.
participants (6)
-
Daniel F. Kudwien -
Earl Miles -
Gábor Hojtsy -
Jose A. Reyero -
Ken Rickard -
Konstantin Käfer