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

[Kieran Lal]

> 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.

> 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.

> Still, same situation but a problem on your end. Those links in the
> admin/help you are creating will die.
>
> This is just one of the reasons that it seems to me that the  
> process for
> this has become too complex right now. If you'd like, I can outline  
> how
> to simplify all of this in a separate post. I think the direction  
> we are
> heading now is
> a) taking too much effort
> b) will be difficult to maintain
> c) has so many workflow processes going on that it's taking away time
> from responding to and developing the docs themselves. For instance, I
> respond to writing *all the time*. LOL. I would be more than happy to
> give feedback on lots of documentation (such as the problem with
> defining forums in terms of containers, rather than forums as forums
> with containers as a special case), but we need clear processes and
> documentation specs to do so.
> d) is trying to be representative of multiple approaches to
> documentation process and development when finding a unified approach
> that works for everyone is best. outlining everything is a must for
> doing this.

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'd be happy to review your suggested outline.

Kieran

> Charlie
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>