[drupal-docs] Versions and translations management for handbook pages

[Charlie Lowe]

I read that thread. Thought you did a pretty good job of fielding answers :)

I think Ber said it best,

"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."

These are issues that have been around for awhile and might not easily 
get solved today or tomorrow.

But some of Gerhard's concerns were more focused directly on 
documentation because by shortening the help text and providing more on 
drupal.org, that means what is on drupal.org is not part of the hard 
coding for translation. And then with versioning up until now, because 
the longer help text has been within the code, somebody using Drupal 4.4 
even though documentation on drupal.org has been updated still has their 
version of documentation within their site.

Obviously, longer help texts in admin/help would be one way to preserve 
versioning. But we've gone to shorter help text because they are easier 
to code. However, translaters are not limited by this. I change the 
"create content" page all the time. Not because I'm translating, but 
because I'm providing different meaning. Similarly, translators can 
include longer texts in their admin/help, translating both the original 
code version and whatever they want from the handbook. To assist 
translators with this, we can use the admin/help as the introductory 
section of each module/feature help in the handbook and design the rest 
of the more involved documentation so that it naturally follows and 
supports the admin/help (single-sourcing, remember?)

As for versioning, Djun can create a pdf at any time. That helps for 
maintaining a version on drupal.org, but not for the links to the longer 
admin/help. In the long run, this is a major flaw with the admin/help 
strategy of shorter texts. I'd say the solution is to maintain the docs 
in the Drupal handbook and somehow they have to be imported into the 
admin/help in full (as was suggested in that discussion). One option not 
discussed in that thread is to automate it through the locale module. 
Provide a language file which replaces all the short versions with the 
longer ones.

The other thing that Gerhard was concerned about was that the admin/help 
is being changed "within" a Drupal release cycle. Translators can 
normally count on it remaining the same througout major release updates. 
Looks like from now on, documentation in the handbook needs to work 
toward following a similar release cycle with a documentation sprint at 
feature freeze time on the next version.

Kieran Lal wrote:
> Hi, I sent a note to the Drupal-dev list giving them a heads up that  
> admin help was going to be submitted soon.   Gerhard came back with a  
> number of questions that need to be addressed.
> 
> 1) If translators translate admin help and they link to translated  
> handbook pages, where will the translated handbooks reside.  Will we  
> create branches of the handbooks?
> 
> 2) How will we version admin help documentation?
> 
> 3) How will we show users documents for each version of Drupal?
> 
> 
> Ideas? Comments?
> 
> Thanks,
> Kieran