[drupal-docs] plans for moving forward with Drupal docs

[Robin Monks]

> 
> ...
> * We have a better set of collaborative authoring tools and
> communication technologies here on drupal.org--forums, project issues,
> collaborative, book mailing lists, etc.--than almost any distributive
> collaborative authoring project ten years ago. We can write effective
> documentation with what we have.


May I also suggest that some focus go to moderating these resources? Or if 
not moderation, so form of community accountability and organization. It's 
great to have people writing large amount of ASCII, but if their is no 
moderation of this, we could end up with misspelled, off topic issues. Just 
a thought.

...
> 
> Right now we have documentation construction spread across a wiki and
> two versions of the handbook. We don't have a clear process for
> submitting documentation. Not only that, but most of what we have been
> doing is hidden from the rest of the community unless they happen to be
> on this mailing list (and in some part on drupal-devel).


If I might butt-in here, some other opensource project like
OpenOffice.org<http://OpenOffice.org>have specialized teams of
documentation writers (similar to what is proposed
with drupal-docs). They have a large scale web system set up, "CollabNet" me 
thinks. It may be worthwhile to look at their system, and see how they 
address some of these issues.
...

> 1) Where does documentation created by the drupal-doc team reside and
> get constructed? This would include guidelines for producing
> documentation, admin/help, handbook text, etc.


Documentation on writing documentation may end up being longer than the 
documentation itself. A few notes here:
- Shouldn't the documentation in drupal.tar.gz and
drupal.org<http://drupal.org>be kept separate?
- drupal.tar.gz should contain a system to access
drupal.org<http://drupal.org>docs from the interface.
- drupal.org <http://drupal.org> documentation writers should have a meeting 
in IRC to talk about some of this.

...
> 
> ... If someone wants a wiki, find a way to
> build a proper one into Drupal. I'm sure everyone is in favor of that :)


Hmm *writing on paper* "make wiki.module functional..." :o)

This helps out with (2) a lot since it leaves us with fewer options. The
> Drupal handbook will obviously be the repository for our documentation.
> And we have a few means to discuss proposals and drafts of
> documentation--mailing list, forums, and project issues. We just need
> now to outline how we will use these technologies. Once we do, I'll
> writeup guidelines so that we can tell new drupal-doc participants:
> "read this to know how to get involved."


Yet another note... There should also be a style guide, similar to 
freesoftwaremagazine.com/write_for_us/<http://freesoftwaremagazine.com/write_for_us/>because
we want a moderate amount of high quality docs, instead of miles of
low quality junk that users hate to read.
...
> 
> 
> don't want to produce an entire new collaborative book for every version
> of Drupal each time there's a new release just so those links work. It
> looks like the versioning problem is not going to be resolved until
> someone comes up with a technological solution.


A note here, Mambo uses a XML-reading system to pull the docs from 
http://help.mamboserver.com and display the latest version directly in the 
Mambo admin panel. Simple, and effective.


> There is a better way, a more efficient way, one that is a writing
> solution to this problem. Bryan posted an outline of the About section
> for V2. I just posted a separate restructuring proposal for the original
> handbook About section. Whether or not we have a V2 version of the book,
> a proposal of some kind--an outline of the new book structure with some
> thinking behind the structure--is a way for everyone to be involved in
> the process: Anisa, Djun, Bryan, Kieran, Robin, Andre, Dries, etc. We
> have a huge resource of people who can help with getting large sections
> of the book outlined before writing begins; proposals such as these are
> commonly used as a starting point to manage large projects effectively.
> Dries has already asked why don't we just rework the original book. This
> is the means to do so.


I'm a technical writer, so I'll be helping As Much As Possible.

Now I got to get back to pending issues...

Robin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050519/70583186/attachment.htm