[consulting] Basic doc for consulting clients

Thomas Barregren thomas at webbredaktoren.se
Sat Oct 28 15:06:21 UTC 2006


Michelle Cox skrev:
>> But to start with, I think it
>> is better to work within a sandbox, and wait to formally publishing it
>> on Drupal.org until it is judged ready. Why? I don't know if anyone else
>> feels like me, but I think it is intimidating to publish something which
>> for a fact will be scrutinized by many critical people. I therefore tend
>> to withhold my work until I'm dam sure that I can stand for it. If more
>> people feel like me, it will have a restraining influence on a
>> collaborative effort such as writing a new customer oriented
>> documentation. But if we work on a collaborative document clearly marked
>> as a sandbox (or draft or pre-alpha or whatever), then I and probably
>> many more would feel much easier to contribute in an early stage of
>> witting, and thereby reducing the risk of duplicated effort and increase
>> the chance of constructive criticism. Am I  talking through my hat?
>>     
>
> I'm doing the same thing with the new user docs I'm writing. They're on my 
> site until they're good enough for Drupal.org.
>   

Good to hear that I'm not alone. :-) But for writing the client 
documentation, I suggest following principles

    * a collective document ownership (cf. collective code ownership
      <http://www.extremeprogramming.org/rules/collective.html> of XP),
    * collaborative editing
      <http://en.wikipedia.org/wiki/Collaborative_editing> through a
      wiki <http://en.wikipedia.org/wiki/Collaborative_editing> or a
      collaborative editor
      <http://en.wikipedia.org/wiki/Collaborative_real-time_editor> and
    * an encouraging attitude towards editing others writing (see for an
      example all contributions
      <http://en.wikipedia.org/w/index.php?title=Drupal&action=history>
      made to the single Wikipedia article about Drupal).

So instead of having several efforts scattering all around the web, I 
hope we all together can pull in the direction of creating an industrial 
strength documentation of how to maintain a Drupal site.


>> From one thing to another, it could be argued that this discussion
>> should be held on the documentation mailing list instead of here. But I
>> think that is a less good idea, at least for now, since we are talking
>> about documentation for consultants' customers. If we move this
>> discussion to the documentation mailing list, I'm afraid we will miss
>> many valuable and well-informed opinions.
>>     
>
> If you aren't willing to move to the doc list, at least cross-post there.

It is not that I am unwilling to post on the doc list. I just thought it 
could be a point to be in a less hurry to move the discussion from the 
consultants' mailing list, since we are talking about a documentation 
geared to the demand of consultants' customers. Maybe I am wrong. :-)

Another idea: Should we  setup a group at http://groups.drupal.org/ for 
this purpose?


>  
> There is currently a major effort underway to redo the handbook and it would 
> be nice to have the doc team involved in this effort.
>   
I've registered myself to documentation at drupal.org.


Regards,
Thomas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/consulting/attachments/20061028/18fb5927/attachment.htm 


More information about the consulting mailing list