[drupal-docs] Regarding the drupal help documentation

Tue May 10 16:34:32 UTC 2005

Below please find a thread regarding the effort to improve the Drupal 
help system.  Please excuse my lack of knowledge, stupidity and refusal 
to do thorough research before jumping into this matter - but I wanted 
to *do* something and now that I have I feel like we can have a 
conversation about it.  I'm copying a thread from over in CSL land - for 
reasons that I think are unfortunate, but obvious - comments welcome -

Hello all,

Welcome to my world! :)

I have been on/off list with Kieran regarding the documentation project 
(and my participation).  I feel strongly that we should have this 
conversation on-list.  I really applaud Kieran's efforts to make this a 
cleaner more friendly and effective process, however I also want to make 
sure that the community has a chance to learn from this dialog (and that 
I have a chance to learn from all of you).  Some may feel that this is 
all too raw - I would suggest you just skip over it if that is the case 
and see what we come up with later.  For those of you with input I would 
be really interested to hear what you have to say.  First some background -

After being a total pain to Kieran on this list I decided I better 
actually *do* something, otherwise my credibility would sink even lower 
:).  So I wrote the following last night -

http://dev.bryght.com/t/wiki/BlockHelp

I didn't understand how to make the text any less complete than it is 
and still have it be useful.  I got a perfectly reasonable response from 
Kieran this morning - to the effect that it is too long - not 
surprising, here's my (longwinded) response:

I have no problem with this being cut up - yes it is long - however I 
would argue that this is an appropriate length to describe the 
functionality of these screens in the "help" section.  My experience 
with this stuff is that there isn't much place for a "quick" guide - 
either you understand what is going on or you don't.  The "quick" 
explanations are frustratingly terse and simply bring up more questions 
than they answer - in general if you can understand the help screens 
then you don't need to be reading them.

Again - I'm not trying to be difficult - but I'm pretty sure I'm right 
about this.  That being said I would love it if you or someone else 
could edit this down and come up with a complete yet shorter description 
of th functionality.  Another thing that is woefully missing is a link 
between the "Help" documentation and a way to get more documentation.  
In short I believe that the current "in drupal" help concept is broken -

1) Shouldn't be hardcoded in the code (or at least should be broken out 
into its own php file with some sort of "override" mechanism).
2) Should be more complete - I think the "short help" concept simply 
doesnt' work for this application.
3) Needs to be a navigable part of a larger whole (i.e. linked into a 
comprehensive help system).

I realize that this may be out of scope - but I don't believe in 
half-measures when something is as broken as this.  I'm happy to be 
proven wrong and I can certainly get with the program once I get 
situated correctly. I would recommend the next steps:

1) Someone should edit down what I've got - I will either disagree or 
see the error of my ways - then I can start to kick out the short 
descriptions as you envision them.
2) I may never agree - in which case you should feel free to use my copy 
in any way you see fit - I would be honored.
3) Buy me a beer and get me with the program.

Again - kudos for taking on such a rough project - and don't get me 
wrong - I'm on your side ;).

Lastly - this converstation belongs at drupal-docs - not here :)

Dan

>
>>
>> Understood, but you are saying we can do this in 30 minute chunks - 
>> so I assumed that there couldn't be much of a startup cost.  I don't 
>> mean to be persnickity here - but I would like to contribute - but I 
>> would like to just start writing - it is really much easier for me 
>> that way.
>
>
> You can really wear a guy down :-)
>
> Take a look at these tables in the wiki.  
> http://dev.bryght.com/t/wiki/DrupalAdminHelpDocumentation
> http://dev.bryght.com/t/wiki/DrupalContribsAdminHelpDocumentation
>
> There are 60 applications, err modules in these tables.  I'll take a 
> sample from the table.  
> Help write these pages     Check these docs                            
>     link to admin interface       admin help docs          Link to 
> handbook V2 page
> EventHelp?                          event                              
>                          /admin/settings/event       
>  /admin/help/event        event
>
> Let me walk you through it.
>
> EventHelp? -> Is a wiki page where you should write the admin/help 
> documentation.  This documentation should be one or two paragraphs.  
>  There should be links.
> event -> This links to cvs where you can download the entire 
> application package.  You want to browse through this because there is 
> often good documentation in install, readme, and upgrade documents.
> /admin/settings/event-> This is the link to where you can administer 
> event.   You want to create a link in the admin/help/event 
> documentation which is an internal link users can click on.   Ideally 
> this link would be named to work in a single window.
> /admin/help/event-> This is the most recently tagged application with 
> admin/help.   It also links to my test site so you can read the 
> documentation live on a drupal site, with an account upgraded by me ;-)
> event-> actually links to the event page in the new configuration and 
> customization handbook.   That page is currently blank, but a crack 
> team of document writers is about to pounce on it.
>
> So in thirty minutes you read the documentation, play around with the 
> app write a couple sentences and make a couple links.   If necessary 
> you do a google search on site:drupal.org applicationname or 
> site:civicspacelabs.org applicationname and read the forums to find 
> your answers.   
>
> A crack team of documentation ninja's suddenly pounce on your wiki 
> page and wrestle application maintainers into accepting the patch.  
> POOF.  Drupal is usable and has great documentation.
>
> Cheers,
> Kieran
>
>>
>> Dan
>>
>>>
>>> On May 9, 2005, at 6:06 PM, Dan Robinson wrote:
>>>
>>>>> If you are interested in helping please contact me to volunteer. 
>>>>
>>>
>>> Dan I couldn't explain everything in one email.  That's why I said 
>>> contact me. 
>>>
>>> Cheers,
>>> Kieran
>>>
>