[drupal-docs] Troubleshooting FAQ

[Richard Eriksson]

On Thu, 10 Mar 2005 12:24:01 -0800, Kieran Lal
<kieran at civicspacelabs.org> wrote:
> I think we have a responsibility to both provide some leadership and to
> raise the quality of documentation in open source software.
> 
> In my opinion the postings combined with documentation present an
> overwhelming experience for new comers.  I think a wiki is a much
> better place for collaborative document editing.

Probably correct, that's why we have a wiki at http://dev.bryght.com/
for people to put stuff in and edit.  For the documenters themselves,
absolutely, a wiki is the best choice.  But a wiki as a "final"
product for users, I like the idea of using a wiki for drafts and
'unofficial' documentation, but for official documentation, using the
software itself to show that you can document something (anything, not
just an open source project) using a core module is a powerful
demonstration of that software.

> I would encourage you to consider tackling smaller projects.   A
> smaller project can push what is expected in of documentation in open
> source software.  Troubleshooting for a system as complex as Drupal and
> dependent on so many variables is a very large task.  Perhaps if we
> focused on a smaller subset and tried to raise the quality of the
> documentation in a few specific areas we could provide the community
> with a benchmark of how good it can be.

Which is exactly what I propose in this specific case.  I want to
improve the troubleshooting section and at the same time using that as
a template for a process where we create or update book pages using
information taken from the answers in the comments to forum posts (or
wherever).

> Something narrow such as Trouble Shooting menus, or blocks with
> excellent visual examples and links to live sites could be very
> valuable.   I believe that a focus on quality will attract people who
> want to participate on higher quality project the way we have seen high
> quality developers get attracted to Drupal Core.

+1 to visuals and +1 to improving the quality.  I'm just suggesting
that in this specific case, we move forum posts in the troubleshooting
FAQ to fully qualified book pages with the answer in the node, rather
than forum posts with question in the node and answer (maybe, not
always the case) in the comments.

-- 
Richard Eriksson
Bryght Community Support
http://support.bryght.com/