[drupal-docs] Idea - move help text out of code into database

[Charlie Lowe]

I think whether or not the documentation is hardcoded or not is up to 
the development team. What we need to do is facilitates the process by 
which we can hand off to them the documentation that they need. They can 
then decide whether to handcode it or not. This is sort of why I 
suggested a sort of single-sourcing approach. Previously (although I 
can't find it now), someone suggested an outline for the handbook for 
modules. This is what I would do (sorry I can't find the other one; 
google desktop failed me ;)

Introduction (on the main page, just 1-3 paragraphs)
- Overview of features
- In depth explanation (just for some modules)
- HowTo's (if available)
- Configuration tips/troubleshooting (if available)

This is obviously open to revision, but the idea is that this would be 
the main structure for all the items listed in the "Drupal modules and 
features" section (http://drupal.org/node/279), including core and 
contrib modules. Some of these items above might end up with subpages. 
Not all modules would need this in depth a structure. But, the 
Introduction and Overview of features would be constructed such that it 
fits in the admin/help. In some instances, developers might choose to 
include more (but we can leave that up to them).

Then, when we update the documentation, we post an issue for developers 
to plug it in as a revision to the admin/help. They take it from there. 
Whether or not it is hardcoded in doesn't matter for us as documenters. 
Developers can decide what is the easiest way to implement it. We just 
have to provide it.

For an example, this piece of documentation for the sprint fits that model:

http://dev.bryght.com/t/wiki/BookHelp

It has an introduction, overview of features, and a howto.

This also gives us our plan for development. The introduction and the 
overview has to be done first. We add in howto's if they are available 
or we happen to be writing them anyway for some other purpose. But we 
don't worry about developing more docs until those are done first.

We also may reach a point where we limit how much is included there: how 
much "howto" and configuration tips, etc. More important than the volume 
of documentation is that we arrive at a place where we can maintain the 
documentation, be able to update it readily for new releases. So for 
instance, a documentation sprint at codefreeze for a new release, where 
our first priority is to update all the introductions and overviews so 
that it can go into the admin/help.

Charlie


puregin wrote:
>      I'm going to re-float here on both lists the idea of having each
> module's help texts provided within the Drupal database, as opposed to
> being hardcoded in.
> 
>      Advantages: the help text documentation would be
>         - easier to maintain
>         - easier to translate
>         - easy to tailor to user's experience level and preferences
>            (tag each helptext with a 'User experience level" vocabulary
>             and select the text according to the user's preferences)
> 
>      I think it would make the code easier to maintain also.
> 
>      Code review and documentation review could occur
> independently.
> 
>      Comments?
> 
>      Djun
>