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

[Charlie Lowe]

 > People are
 > working within the current handbook structure to improve the content
 > and people are working in the new handbook structure to build new
 > content.  Either way that's progress.

I'm not sure it's that simple. One of the things that I think we should 
consider is why we are rewriting. Restructuring is one thing, but if we 
are revising the texts and changing the content, I think we should 
remember that much of the Drupal handbook is the product of community 
development and consideration of a target audience. I say this, because 
I think we should avoid the assumption that anyone of us can just 
rewrite a section and that it will be improved since we are one and 
those the text that was created before was the product of many.

Now everyone's intent is definitely to improve the documentation. But 
instead of going with the approach "let's rewrite it" and then discuss
it, it will likely be more productive to do some discussion up front of
things like

* target audience
* the ways in which the current text targets that audience
* the ways in which the current text could be improved in terms of
targeting the audience
* new goals for the revised version
* formatting/style/structure for the revised version (beyond that of the
style guide)

In some cases, it may be useful to provide an example rewrite for a
section, too. So for an example, let me pick on Kieran since I know he
has a thick skin and won't take offense ;) :

So with the admin/help rewrites, I would say that a better process would 
have been to for Kieran to

* produce a sample or two of admin/help section
* in the process of creating that admin/help section, write a document 
such as the one he just produced for "Round 2 of Documentation Sprint" 
to include also some audience analysis of existing documentation and 
proposed changes (if needed or intended)

If these are then offered up for discussion, as a group, we can offer 
suggestions before all the documentation is in the process of rewriting, 
making it easier to achieve improved documentation in the initial 
rewrite. It also will assist in allowing others to jump in.

Charlie






bryan kennedy wrote:
> I am replying to various points outlined in the previous comments.  I  
> think:
> 
>      -Rewriting the handbook inside the current structure will lead  
> to a slow tedious process.
>          -This process will still create dead links since we are  
> restructuring not just re-writing.  Pages will move, whole sections  
> will disappear.
>      -We need to be able to work on a fresh copy that is advertised  
> as unfinished.
>      -I think (and have suggested) we should freeze the current  
> handbook.
>          -Yes, that means that if you see an error it will go unfixed.
>          -That error or new documentation will be built into the new  
> handbook.
>      -Once this handbook is at a acceptable level of completeness, it  
> will become the new handbook
>          -Over the period of a weekend (or some other very short  
> period of time) we will fix all the links (aliases) to the old  
> handbook to appropriate new content.
>