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

[Charlie Lowe]

Kieran Lal wrote:
>>So the handbook is now useless to me since if I link to the old  
>>stuff, the links will rot. If I link to the new stuff, well there's  
>>nothing there yet.
> 
> 
> 'useless' is a term that I would prefer not to see used when  
> describing previous volunteer efforts or upcoming volunteer efforts.   
> You point is taken, but let's tone down the rhetoric and come up with  
> some practical solutions.  For example linking between old and new  
> pages is a reasonable solution.  Also, this is a massive effort doing  
> any little thing 60 times is basically out of the reach of almost  
> everyone.  So let's accept that a volunteer effort on a open source  
> project will not be perfectly seamless.   The ability to tackle  
> projects of this magnitude in the past is exactly why things are patchy.

Granted. Lots of people are expending a lot of effort. It is a massive 
undertaking, but the process right now has inherent flaws which I 
believe, with simplification, can be greatly improved. For example, your 
suggestion

"For example linking between old and new pages is a reasonable solution."

Is a usability issue. One text is much better for users.

And yes, useless is a strong word, but the ability to be able to link to 
and develop documentation based on the handbook is seriously reduced. 
For example, I'm in the process of putting together local documentation 
for the project I'm working on. Suppose I see in the main Drupal 
handbook that a couple of tweaks to the text would benefit the project 
I'm working on and the Drupal handbook. Where do I put my revisions? 
That decision should be based upon whether we are copying pages back or 
not (which is not clear at the moment). For me, the easiest process 
would seem to be to revise the existing Drupal handbook page and link to 
that. If existing pages are merely moved around (i.e., new books 
top-level pages are just old book section pages), the linking is preserved.



> 
> 
>>I had also thought the plan was to create new handbook pages and  
>>copy them over, but that seems to be different from what you are  
>>suggesting.
> 
> 
> I am actually not suggesting anything about how the new pages are  
> created.  Although I did ask to create the pages and was given  
> permission.  I do believe there are efforts underway to bring  
> existing pages up to the authoring guidelines and then move them to  
> the new books.

See the discussion went back and forth for a while, but then the new 
most recent thing I thought I heard was that they would be copied over. 
Not sure, though.


> 
> All valid points.  I don't want dismiss any of them.  We are probably  
> going to have someone to blame for all of this as soon as the  
> documentation dictator is appointed.
> 
> "Man the docs workflow, and process really sucks right now what was  
> {Anisa, Bryan, Djun, Charlie, !Kieran} thinking"
> 
> I know it's frustrating, not having things as good as they could or  
> should be.   But all your constructive criticism is teaching me a ton  
> about writing documentation.  I am sure the others reading this are  
> learning a lot as well.   But let's make sure you are not completely  
> blocking out the light at the end of the tunnel.   Otherwise we are  
> going to go back and write 50 000 words about how we should write  
> documentation instead of writing 50 000 words of documentation.


I'm actually less interested in being documentation director than I am 
in creating a process by which we can easily create, maintain and use 
the documentation.  Like the Drupal develop process, I believe we need a 
simpler process than what we are currently engaged in at the moment.