[documentation] [Documentation feature] Revolutionary, Innovative, Alternative approach to Drupal documenation?

[Eaton]

Issue status update for 
http://drupal.org/node/106720
Post a follow up: 
http://drupal.org/project/comments/add/106720

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     feature requests
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  voipfc
 Updated by:   Eaton
 Status:       active

"Instead of real content there will be links to contributors websites,
probably wikis, where their versions of the topics will be created.
Readers can then vote on which ones are the best and Drupal documentors
can select which of them will go into the Official Handbook, which may
not necessarily be those with the top votes.

"
Here's a secret: joining the drupal documentation team is not
difficult. You do it by Clicking this link [1] and typing text that
explains something that was previously not explained, or not explained
well.


There is a hierarchy already; there may be opportunities to improve it,
but those are opportunities for specific changes, not a revolutionary
new approach.


I have to concur with webchick; distributing the docs around the 'net
is a recipe for more confusion and linkrot. Not only that, it would be
nearly impossible to update outdated information if it wasn't on
drupal.org. Any maintainer with the knowledge and dedication to maintain
a separate off-site doc site, and keep it up to date, would be able to
work just as easily here on drupal.org, with the added benefit that
others could help them.
[1] http://www.drupal.org/add/node/book




Eaton



Previous comments:
------------------------------------------------------------------------

Thu, 04 Jan 2007 01:53:43 +0000 : voipfc

This is my idea of how Drupal documentation should be created. It is
further explained in this forum topic - A Revolutionary proposal for
creating documentation [2]  relating to this topic in another one Drupal
documentation: A constructive criticism.


The right approach here is not for everything to be created at
drupal.org, but for Drupal documentors to create a document outline,
with chapters, topics, and desired content specified. Even this part of
the process can involve the community.


Instead of real content there will be links to contributors websites,
probably wikis, where their versions of the topics will be created.
Readers can then vote on which ones are the best and Drupal documentors
can select which of them will go into the Official Handbook, which may
not necessarily be those with the top votes.


Drupal documentors can also create their versions, but in their own
sandbox, which are also linked to just like the others. It could even be
the case that some of the unofficial guides may be so much better than
what the Official guys are producing that they may even decide to apply
their efforts to those instead into the final Official version.


After some time each chapter or topic will be well fleshed out and the
best ones can make it into the Official Handbook. If the manual can also
be developed around a real or imaginary project, using a real website,
such as the new.drupal.org, that will also help.


The approach here is for progress to be through small but well focused
contributions, in well defined areas. Having thousands of cooks will
spoil the banquet, it the cooks are divided into small teams with well
defined tasks in preparing the banquet, you will end up with great
banquet.


One thing that we have to realise that Drupal is a moving target and
new versions may come about before the manual is completed. But so long
as the Drupal version involved one provides a strong enough foundation
for developers to work on, once they create a project with that version
they might even stick with it for good where that project is concerned.
Module breakage and all that.
In any case the links can point to the appropriate versions for newer
an older versions.


My message here to Drupal leaders is: create the structure, setup some
guidelines, provide some advice and control, and the community will do
the rest.


Many hands make light work.


Just as with modules, business can sponsor some pages by providing
staff or paying bounties to support their creation, and have their shiny
logos shining out brightly from the pages if they want.


The Component selected was Developer Guide which reflects my area, but
it is equally applicable to the User and Admin guides.
[2] http://drupal.org/node/106309#comment-185402




------------------------------------------------------------------------

Thu, 04 Jan 2007 02:16:40 +0000 : Chill35

My G** you STOLE my idea (LOL). I SWEAR I had this very idea today...


Really there will never be better doc out there than off-site
(initially, when it's created), on other people's web sites, and in
people's intended-for-publishing books. 


I suspect that a few people involved in Drupal.org are working hard on
the book that's coming up in April... NOT putting in their effort in
improving the documentation here... (their right)... and don't tell me
it's for the money, it's mainly for other intangible benefits AND
money... lol...




------------------------------------------------------------------------

Thu, 04 Jan 2007 02:28:58 +0000 : drumm

I know a few technical authors. Writing a book isn't profitable in terms
of money given the large time investment.


Good work on Drupal itself has come from Drupal-related-authors. They
have to take a close look at the system for research and writing. That
results in improvements to Drupal when they notice something that should
be changed.




------------------------------------------------------------------------

Thu, 04 Jan 2007 02:41:00 +0000 : webchick

-1 to Drupal documentation being scattered all over the Internet on
random sites that may or may not be online in a few months' time. This
will only lead to link rot, fragmented data, and non-centrally
searchable information. Ugh.


We have an outline already. It's called the handbook. Anyone can create
handbook pages. Anyone who asks can edit handbook pages to refine and
improve them. People are more than welcome to contribute stuff they've
written on their personal/business sites. People are also more than
welcome to collate links to off-site tutorials that are helpful. If you
have an alternate outline idea for the developer's guide, propose it to
the documentation mailing list. If your company wants to pay to have
people improve the documentation in one area, propose that too.


Sorry, but I don't really see the point.