[documentation] Babies, Spoons, Food and Funny Faces

[Dries Buytaert]

On 07 Jan 2006, at 00:23, themacgeek wrote:
> I will continue on with your suggestions, though I would still  
> assert that this method, while it is a good short term solution for  
> addressing the situation, I feel a more structured system would be  
> better.  In much the same way that the Drupal code is handled, I  
> see a similar system as being more effective long term.

Only few people have a good overview of the entire code base.   
SImilarly, only few people have a good overview of the entire Drupal  
handbook.  As a result, new people don't know where to start.  They  
want a clear roadmap.  Unfortunately, even with a roadmap, they'll  
find themselves lost because no one is supervising or giving concrete  
instructions. Plus, even with a roadmap, they still don't know what  
others are working on.  So while a roadmap is nice to have, it  
doesn't solve the key problems.

The better solution is to use the issue tracker.

It will help you identify tasks, it will give you a sense of  
direction, it will act as a knowledge base, and will facilitate  
communication with fellow documentation writers.  It is an  
_essential_ communication tool.  Without it, the development team  
would be in the same situation as the documentation team.  We'd feel  
lost.  We wouldn't know what to do or where to start.

So let's do a better job using the issue tracker for documentation  
writing purposes.  I took the liberty to make some changes:

1. I updated the mailing list footer to include a link to the issue  
tracker.  This will make it really easy to access all pending  
documentation tasks.  (Hope it worked.  This is the first test e-mail.)
2. I updated the 'Quick links' block shown on every book page to have  
a link to the issue tracker.  The name of this new link is 'Report  
documentation issues'.  This will make it easier to file bugs against  
the documentation, or to access the issue tracker from the website.

--
Dries Buytaert  ::  http://www.buytaert.net/