[drupal-docs] Administrator's guide - Make Task Orientated

[Robert Castelo]

On 13 Jan 2005, at 06:48, Boris Mann wrote:
> Agreed. I've always thought there should be a features section
> (covering core Drupal) and then contrib features or something like
> that -- basically the project description, but perhaps with more
> detail, and then how-tos underneath each module.

Good idea, a lot of Drupal functionality now comes from the contrib 
modules.

I think documentation for contrib features should be kept separate as 
much as possible though, as modules come and go with each Drupal 
release - it would be a nightmare trying to pick through all docs 
trying to keep the info current with module releases.

One way we could do this is to have the book navigation define the task 
section, e.g. "User management", then add a page for a module that can 
be used for that task, e,g. "Automember module".

Module pages could be weighted to come below core pages.

It might also be useful to give indication of what task module 
performs, so instead of just "Automember module" we could standardise 
to "Role management (Automember module)". That way navigation can be 
useful for admins looking for info for task or module info.

One argument against this is that we would be duplicating some of the 
info in Projects - but Projects is not suitable for a task based 
approach.



> Frick. We need some way of nailing up some of this stuff as to-dos,
> but basically the only way to do it is to start messing with the
> structure of the handbook. But we need some sort of consensus (or
> close to it) on what the structure of the hand book should be.


To do:

1) Agree on structure

2) Create new structure

3) Move existing pages into new structure

4) Edit existing pages

5) Add new pages

6) Delete comments - move info into pages (where useful)


> (BTW -- pretty much our entire admin guide [1] is structured as "how
> tos" without referring necessarily to which "module" powers it)
>
> [1] http://support.bryght.com/adminguide


Nice!

One suggestion though, cut the length of the titles - the navigation 
(book and breadcrums) should inform readers that they are in a "How to" 
section, so no need for that in title.

It's also easier to scan through a list of navigation links if first 
word(s) are the object you want to perform task on:

"Create Roles and Permissions"
"Create an Articles Page"
"Create a Book Page"
"Enable, disable, and set order of side blocks"

=>

"Roles and permissions management"
"Articles page creation"
"Book page creation"
"Side block management"

..this way you only need to read first word not scan entire line if you 
were looking through list of links for how to control side blocks.


Best regards,

Robert [MegaGrunt]