[drupal-docs] Drupal handbook, admin/help, etc. -- a single sourcing approach

[Charlie Lowe]

When Dan wrote concerns/questions about the length of his documentation, 
I suggested the following approach:

1) Introductory paragraph describing the thing (for those that want the
general description)
2) Section(s) dealing with more detailed conceptual things (for those
that have read or want to skip the introduction and want more detail)
3) Howto's for doing the harder tasks (for those that have muddled
through trying to do it on their own and are ready for the detailed
instructions).

Since there was little response to it, I get the feeling that people 
think it's out of touch with what needs to be accomplished for the 
admin/help and for the handbook. Well, not if you see it as a single 
sourcing approach.

Previously, and there are still a few handbook pages this way, many of 
the admin/help pages mirrored the Drupal handbook pages--or more 
correctly, the Drupal handbook pages were pulled directly from 
admin/help using a php script.  Whether or not the admin/help pages are 
too long or too short, the approach of single-sourcing the 
content--using a master document to pull from to create other 
documents--is a good method of constructing the handbook that minimizes 
the need to write separate documentation; it's a pragmatic way of 
maximizing the efforts of documentation writers.

So, for example, each module section in the handbook should have a main 
page with a short introduction and be broken into sub-sections as Djun 
has been doing recently. That introduction, and maybe other sections 
could/would end up in the admin/help. And the advantage of this is that 
when someone like Dan starts writing a longer text, if it's structured 
correctly, it will end up being useful rather than saying: "oh, this 
needs to be a lot shorter." And when someone revises text in the 
handbook that is in admin/help, they can file an issue which says 
"please replace the existing admin/help text with the new stuff." No 
need to have a wiki and a handbook (and another version of the handbook) 
and admin/help text different from handbook text--the process is too 
convoluted right now. Even if the result is slightly more usable text, 
the downside is that it's not very practical and will likely inhibit the 
creation of that text.

Maybe this was the intention from the start for the admin/help. I don't 
know. It's next to impossible to follow all the discussions that have 
been going on about documentation and be sure what has been decided.

Charlie