[drupal-devel] Admin Help writing instructions - 60 patches coming soon
Hi, last week I ran an admin help documentation sprint for 60 modules. Through lots of discussion and various different attempts we have arrived at some writing instructions for what should be in admin help text. We probably still have a draft or two to do. I want to make sure that the development community is going to be behind this effort when the patches come. This would be a good time to include your feedback into the writing instructions or the admin help drafts themselves. Everything is in a wiki so edit away! Here are the writing instructions: http://dev.bryght.com/t/wiki/ AdminHelpWritingInstructions Here are the drafts: http://dev.bryght.com/t/wiki/ DrupalAdminHelpDocumentation, http://dev.bryght.com/t/wiki/ DrupalContribsAdminHelpDocumentation We are looking for experts to review to the admin help when we think we have done enough drafts. Please let me know if you would be willing to review documentation to ensure it is accurate. Cheers, Kieran
On Mon, 16 May 2005, Kieran Lal wrote:
Here are the writing instructions: http://dev.bryght.com/t/wiki/ AdminHelpWritingInstructions
I had a quick read and found that you plan to maintain the longer doculemtation pieces on drupal.org. I am not opposed to this, but I'd like to know what your solutions are to a) translations b) different Drupal versions. a) Currently, translators can translate the docs for say Drupal 4.6 and be pretty sure that they won't change over this release cycle. With you change, the translation might be improved after the release - unless it is agreed not to do this as we do with the code. b) Different Drupal versions need different docs. How will you show users a set of docs for each version? Cheers, Gerhard
On May 16, 2005, at 7:40 PM, Gerhard Killesreiter wrote: First off, thanks for taking the time to respond. I know documentation is not the most fun topic :-) In general, I think the benefits of the english versions will translate as well to translated versions. Also, I think this a good question for the Drupal docs mailing list. A couple of things that I think will be beneficial for translators will be that the text in the code is going to be reduced and will be much more consistent. I hope that consistency will make for easier translations. Also, I believe the greater reliance on using lists of links will make for more clarity and not require as much translation.
a) Currently, translators can translate the docs for say Drupal 4.6 and be pretty sure that they won't change over this release cycle. With you change, the translation might be improved after the release - unless it is agreed not to do this as we do with the code.
Yes, I see this as an advantage. In the current admin help drafts each page ends with "For further information, read the ....http:// drupal.org/node/####. Translators can link to their own page instead. With regards to versioning we have yet to come up with a solution. We have been discussing it on the mailing list for several months and I know it has been a topic for several years. Thanks for raising the issue, and I'll take it back to the team. The larger issue however, may be the sharp increase in the amount of documentation. There is a strong demand for more contributions documentation and this may become a heavy workload for the translators.
b) Different Drupal versions need different docs. How will you show users a set of docs for each version?
Each version of the module's admin help could point to their own page on Drupal.org. This might get messy, but I guess that's what content management systems are for :-) Cheers, Kieran
Cheers, Gerhard
On Mon, 16 May 2005, Kieran Lal wrote:
On May 16, 2005, at 7:40 PM, Gerhard Killesreiter wrote:
First off, thanks for taking the time to respond. I know documentation is not the most fun topic :-) In general, I think the benefits of the english versions will translate as well to translated versions.
I hope so.
Also, I think this a good question for the Drupal docs mailing list.
A couple of things that I think will be beneficial for translators will be that the text in the code is going to be reduced and will be much more consistent.
That's true.
I hope that consistency will make for easier translations. Also, I believe the greater reliance on using lists of links will make for more clarity and not require as much translation.
Probably. But the idea of translation is to translate all documentation.
a) Currently, translators can translate the docs for say Drupal 4.6 and be pretty sure that they won't change over this release cycle. With you change, the translation might be improved after the release - unless it is agreed not to do this as we do with the code.
Yes, I see this as an advantage. In the current admin help drafts each page ends with "For further information, read the ....http:// drupal.org/node/####. Translators can link to their own page instead.
Where will those pages reside? Is there any plan for this?
With regards to versioning we have yet to come up with a solution. We have been discussing it on the mailing list for several months and I know it has been a topic for several years. Thanks for raising the issue, and I'll take it back to the team.
I had hoped that you'd found a solution. ;)
The larger issue however, may be the sharp increase in the amount of documentation. There is a strong demand for more contributions documentation and this may become a heavy workload for the translators.
I wouldn't worry too much about contrib at the start.
b) Different Drupal versions need different docs. How will you show users a set of docs for each version?
Each version of the module's admin help could point to their own page on Drupal.org. This might get messy, but I guess that's what content management systems are for :-)
We still should have a solution for this before the help pages are changed. My revisions patch will make keeping revisioned information through Drupal somewhat easier. I think that it would be possible to extend it further to also allow for branches. This could help to keep documentation for different branches of Drupal up to date. Cheers, Gerhard
On 16-May-05, at 11:04 PM, Gerhard Killesreiter wrote:
b) Different Drupal versions need different docs. How will you show users a set of docs for each version?
Each version of the module's admin help could point to their own page on Drupal.org. This might get messy, but I guess that's what content management systems are for :-)
We still should have a solution for this before the help pages are changed.
My revisions patch will make keeping revisioned information through Drupal somewhat easier. I think that it would be possible to extend it further to also allow for branches. This could help to keep documentation for different branches of Drupal up to date.
We've never had versioning for docs before. In fact, what we had was out-of-date information or no information at all, with no info on what "version" of Drupal it applied to. We're building the docs now, and aren't going to wait for development unless it gets done in the next 2 weeks. Am I particularly happy with this as a solution? Nope, I'd love to see help texts ship with Drupal that are completely editable, without the hack of having to use locale.module to go from English (Drupal) to English (I edited the help texts). But we're using what's available to us today. 4.6 is likely going to be the first version with decent, fairly complete documentation because of the efforts of Kieran and the rest of the Drupal Docs team. -- Boris Mann http://www.bmannconsulting.com
On Mon, 16 May 2005, Boris Mann wrote:
On 16-May-05, at 11:04 PM, Gerhard Killesreiter wrote:
We still should have a solution for this before the help pages are changed.
My revisions patch will make keeping revisioned information through Drupal somewhat easier. I think that it would be possible to extend it further to also allow for branches. This could help to keep documentation for different branches of Drupal up to date.
We've never had versioning for docs before. In fact, what we had was out-of-date information or no information at all, with no info on what "version" of Drupal it applied to.
We're building the docs now, and aren't going to wait for development unless it gets done in the next 2 weeks.
I wanted to point out where potentials problems might be. As somebody who neither reads nor translates docs this is about as much as I am going to do. Cheers, Gerhard
On May 16, 2005, at 11:04 PM, Gerhard Killesreiter wrote:
Where will those pages reside? Is there any plan for this?
We still should have a solution for this before the help pages are changed.
My revisions patch will make keeping revisioned information through Drupal somewhat easier. I think that it would be possible to extend it further to also allow for branches. This could help to keep documentation for different branches of Drupal up to date.
I don't think we addressed your question adequately yet. I don't know anything about your revisions patch. But there has been great resistance, by which I mean lack of enthusiasm, for formal revision management of documentation. I suspect that it's hard to imagine doing revisions if you haven't written it first. Or it could be that revision tools are believed to be too intimidating. I think that one way of managing the different revisions is right under our noses. Taxonomies, and their young trendy cousin folksonomies. For example, I have been looking at wordpress's documentation site. http://codex.wordpress.org/Category:Stubs http://codex.wordpress.org/Category:Copyedits Perhaps we could set up a taxonomy for the handbook and then allow the docs team and the translation team to tag documents with version numbers, and translations. At the same time we could enable, folksonomies which I haven't used, and allow visitors to Drupal.org to tag forum topics, documentation, and content with tags. I think this best reflects the situation we are in. We have a small team of documenters trying to categorize and produce documentation, then a team of translators who need figure out what they should translate, and finally a large community that could do a lot of the weeding for us. I'll move this idea over to Drupal docs shortly. Cheers, Kieran
On Tue, 17 May 2005, Kieran Lal wrote:
On May 16, 2005, at 11:04 PM, Gerhard Killesreiter wrote:
Where will those pages reside? Is there any plan for this?
We still should have a solution for this before the help pages are changed.
My revisions patch will make keeping revisioned information through Drupal somewhat easier. I think that it would be possible to extend it further to also allow for branches. This could help to keep documentation for different branches of Drupal up to date.
I don't think we addressed your question adequately yet.
I don't know anything about your revisions patch. But there has
The patch is more of a technical matter, but it also changes the revisions UI a bit and allows all node types to have a log message.
been great resistance, by which I mean lack of enthusiasm, for formal revision management of documentation. I suspect that it's hard to imagine doing revisions if you haven't written it first. Or it could be that revision tools are believed to be too intimidating.
Well, we are currently already using revisions for the handbook on drupal.org. We just don't have branches for the various versions/translations.
I think that one way of managing the different revisions is right under our noses. Taxonomies, and their young trendy cousin folksonomies. For example, I have been looking at wordpress's documentation site.
http://codex.wordpress.org/Category:Stubs http://codex.wordpress.org/Category:Copyedits
Perhaps we could set up a taxonomy for the handbook and then allow the docs team and the translation team to tag documents with version numbers, and translations.
This has been suggested in the past but wasn't met with enthusiasm either. I don't recall why, but the open question how the book should be displayed in this case might have been a reason.
At the same time we could enable, folksonomies which I haven't used, and allow visitors to Drupal.org to tag forum topics, documentation, and content with tags.
This would be possible, but I think it is unrelated to the current question.
I think this best reflects the situation we are in. We have a small team of documenters trying to categorize and produce documentation, then a team of translators who need figure out what they should translate, and finally a large community that could do a lot of the weeding for us.
We also need to figure out how to present the created content to this community.
I'll move this idea over to Drupal docs shortly.
I hope you can come up with a solution that is viable for all parties. Cheers, Gerhard
I believe that my suggestions about putting this documentation into the database might help with some of these issues. I imagine that the process would look something like this - - help texts get written and refined by developers and members of the documentation team. The working version of these documents in the drupal.org database would correspond to the CVS version of the code. Better versioning for nodes is a longer-term need, but in the meantime, the existing node versioning would work for 'head', and branching could be done by bulk-copying the nodes. - the script which generates the CVS tarball would grab the help-texts from the drupal.org database and dump them into the database.(my|postgre)sql file (or a separate dump file?) - I'd like to see translated help-texts available on-line at drupal.org also. These would be written and versioned as for the English texts. There would have to be a separate process for getting these translations into the .po files. Actually, what I'd like to see is documentation on docs.drupal.org - a separate server :) I'm also intrigued by Kieran's idea of using xml-rpc or some other method of having installed Drupal sites update their documentation dynamically, or load new translations dynamically. Regards, Djun On 16 May 2005, at 7:40 PM, Gerhard Killesreiter wrote:
On Mon, 16 May 2005, Kieran Lal wrote:
Here are the writing instructions: http://dev.bryght.com/t/wiki/ AdminHelpWritingInstructions
I had a quick read and found that you plan to maintain the longer doculemtation pieces on drupal.org. I am not opposed to this, but I'd like to know what your solutions are to
a) translations b) different Drupal versions.
a) Currently, translators can translate the docs for say Drupal 4.6 and be pretty sure that they won't change over this release cycle. With you change, the translation might be improved after the release - unless it is agreed not to do this as we do with the code.
b) Different Drupal versions need different docs. How will you show users a set of docs for each version?
Cheers, Gerhard
-- Djun M. Kim, Director djun.kim@cielosystems.com Cielo Systems Inc. http://www.cielosystems.com Strategic Software Research Tel: (604) 739-3941 302 - 1298 10th Avenue West FAX: (604) 739-3943 Vancouver, BC, V6H 1J4 Mobile:(778) 895-1379
I'm also intrigued by Kieran's idea of using xml-rpc or some other method of having installed Drupal sites update their documentation dynamically, or load new translations dynamically. RSS looks like a good candidate to me
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 vlado wrote:
I'm also intrigued by Kieran's idea of using xml-rpc or some other method of having installed Drupal sites update their documentation dynamically, or load new translations dynamically.
RSS looks like a good candidate to me
Indeed, I would like to have Drupal installations 'phone home' for the latest available package information eventually too. -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.4 (Darwin) Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org iD8DBQFCidp1gegMqdGlkasRAqkyAJ9lut2ObZoJKIDry2rmCt4SO4NLuACfRAq/ 6iTucVePEsXeQZL8cM0UF6w= =7FdH -----END PGP SIGNATURE-----
Op dinsdag 17 mei 2005 04:40, schreef Gerhard Killesreiter:
a) Currently, translators can translate the docs for say Drupal 4.6 and be pretty sure that they won't change over this release cycle. With you change, the translation might be improved after the release - unless it is agreed not to do this as we do with the code.
in theory, very true. in practise, not. Only a very small amount of these texts are actually translated. So, i am not too sure if we really to bother too much. If we have t('You can do foo and bar here. <a href="drupal.org/link/to/long">Learn more</a>') one can translate that into: You can do foo and bar here. <a href="drupal.org/link/to/translated/long">Learn more</a> or even You can do foo and bar here. <a href="drupal.hu/link/to/help">Learn more</a> IMO that would be more than enough power.I have not seen much po files that actually had all the help translated, but then again, its been awhile since i checked them all ;) Regards, Bèr -- [ Bèr Kessels | Drupal services www.webschuur.com ]
Op 16-mei-2005, om 22:21 heeft Kieran Lal het volgende geschreven:
Here are the writing instructions: http://dev.bryght.com/t/wiki/ AdminHelpWritingInstructions Here are the drafts: http://dev.bryght.com/t/wiki/ DrupalAdminHelpDocumentation, http://dev.bryght.com/t/wiki/ DrupalContribsAdminHelpDocumentation
We are looking for experts to review to the admin help when we think we have done enough drafts. Please let me know if you would be willing to review documentation to ensure it is accurate.
Cheers, Kieran Wow, you did an awesome job on this! I'll review the helptexts within a couple of hours, because I truly want to get this in asap.. What is not very clear to me is how you would like to link to the documentation on drupal.org. Would you like to use the 'more help'- link beneath the helptext itself to link to the extended helptext on drupal.org? I would really like to have some more information on this, while I don't want to rely on the availability of drupal.org a lot..
If you need any help producing patches, you can count on me! This is one of the most important changes to drupal documentatioin in ages! Many, many thanks from you and your co-workers in the drupal documentation team.. Yours sincerely, --- Stefan Nagtegaal http://www.istyledthis.nl/
participants (8)
-
Adrian Rossouw -
Boris Mann -
Bèr Kessels -
Gerhard Killesreiter -
Kieran Lal -
puregin -
Stefan Nagtegaal -
vlado