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

[Charlie Lowe]

LOL. I don't think I have the solutions anymore than anyone else 
did/has. But it would seem to me that the versioning problem for 
documentation is best solved by incorporating the documentation into 
each Drupal major release rather than pushing the problem from there by 
shortening the admin/help text length onto drupal.org (the handbook).

And all of your documentation goals are great. But my feeling is that 
the question of whether or not these improvements would be incorporated 
into longer texts in the admin/help versus shorter texts in the 
admin/help and linking to the handbook is motivated by the technological 
shortcomings of the admin/help section and the process for incorporating 
text into it more so than it was about improving the quality of the 
text. Longer help texts in the admin/help would have achieved most of 
your goals, although perhaps harder to write and implement on 
CivicSpace's current release schedule needs. But we could do it for 
Drupal's next release.

So yes, translators are actually lucky in a sense because they can 
continue to provide versioning of as much Drupal help documentation as 
they want because they are using the locale module.

Djun has been working on finding ways to improve the collaborative book 
for import/export, first step being pdf's. Perhaps this will lead to a 
way to easily import help text into Drupal at a new release cycle to 
overcome the help.module shortcomings.

As to how to incorporate the help text in to the middle of the release 
cycle, yes, I think that if we want to make the process work for 
translators, in the future, we should do a documentation sprint at 
feature freeze and incorporate it then. Certainly it would be optimal to 
incorporate changes in along the way. But, as you have said, admin/help 
has been sorely maintained across major releases; this would be a nice 
compromise, a pragmatic solution, for keeping it updated with more 
frequency that does not require a new technological solution until a 
better one does become available.


Kieran Lal wrote:
> Charlie, I think some of your recap of the reasons for moving to shorter 
> shorter admin help were not quite complete.  You probably know all this 
> but I just want to make everyone is on the same page. The motivation for 
> moving to the admin help standards were: 45% of it was missing entirely, 
> there was already active patching efforts to reduce the size of admin 
> help by the developers, testing indicated documentation was a huge 
> usability issue, we wanted to make the documentation scannable, there 
> were no links to assist users in completing tasks, it was difficult for 
> the documentation team to make changes to admin help, the documentation 
> survey indicated module documentation was the most needed documentation, 
> and since we were writing handbook pages we might as well link to the 
> more authoritative source, the documentation handbooks on drupal.org.
  >
>> Let me see if I can summarize Charlie's response into my questions.
>> 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?
> 
>> >>>The translated documents will now have to be the whole handbook 
>> page, which begins with the admin help documentation.
> 
>> 2) How will we version admin help documentation?
> 
>> >>>We are going to create pdf's of older versions of the handbook 
>> pages with this admin help documentation and archive them on drupal.org
>> 3) How will we show users documents for each version of Drupal?
> 
>> >>>The handbooks will be versioned in archived pdfs.
> 
> 
>> >>> Regarding changing admin help documentation mid-release, we have 
>> to sync the handbook to the release of the software.
> 
> 
> Did I get it right?
> 
> Cheers,
> Kieran
> 
>> -- 
>> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>>
>