[drupal-docs] Round 4 of documentation sprint Admin help: merging into the handbook

[Charlie Lowe]

Okay :) Kieran I talked about quite a few of these things over the last 
few days.

1) The admin/help text links to specific pages in the handbook. If we 
put the admin/help text in it's own section, then we still would have 
approximately 40 empty pages in the modules and features section of the 
handbook for which there is no content. As an alternative, it would seem 
strange to link directly to an appendix instead where there would be 
nothing but duplicate text; no additional pages there for any of the 
content.

2) In many cases, some minor modules may not require additional text, or 
maybe only howto style tutorials. So what do we put in the 
modules/features section? Howto's don't seem appropriate for the main 
page for each module. For the moment, we see the admin/help text 
functioning as an introduction/abstract/shorter definition/executive 
summary for the longer sections, a common practice in other forms of 
document construction. It's an interim solution.

3) It could be quite a while before anyone writes additional 
documentation for the modules for which none currently exists in the 
handbook. Seems easier to work with what we know we can accomplish, 
rather than with what might be (but not linkely to be any time soon).

3) Since the admin/help will be accompanying Drupal core, there's less 
of a need for versioning it in the handbook--users will have it in their 
site--and more of need to version the rest of the modules and features 
text. So I'm not sure that versioning the admin/help text in this 
instance would accomplish much towards our main versioning needs (we 
could certainly debate this later). How to version the other text seems 
more involved than Kieran and I could get into at the moment and outside 
of the main goal for this project, especially since the current handbook 
doesn't provide a solution for versioning. Seems like the versioning 
issue should be part of the much larger restructuring project, and I 
imagine, a point of much debate.


puregin wrote:
> 
> 
> I agree that the larger picture of reorganizing the Administrator's 
> guide
> needs some deliberation, perhaps managed by a team.
> 
> I wasn't attempting to propose a final structure - just provide some
> context for the argument that the new admin help pages should go into 
> their
> own new section(s).
>