[documentation] Re: [drupal.org] FAQ

[Kobus Myburgh]

Hi,

I do believe that sometimes the handbook information is distributed and hidden and bloated, especially answers hidden in comments. I think this means we have two options:

1. Do it the way you suggest, and let the user sift through the comments.
2. Rework the comments into the documentation pages (and possibly rewrite the page).

As for #1, I am not completely happy about that - it defeats the purpose of an FAQ. As for #2, I can do the links think as you suggest, but then rework every page as I link to it. I will create new pages from forum topics that delivers results.

I'll see what I can do.

Kobus


>>> speck at blkmtn.org 4/27/2006 2:51 AM >>>
Why not reverse it.  We hacd sections in the Troubleshooting FAQ but
each of the secitons had so much duplication that I removed the sections
and kept the unique articles.
 
FAQ
1.  Administrator
2.  Troubleshooting
3.  Contributor
4.  User
 
Short answers with links to more extensive articles in the handbook.
This way people who actually bother to read the handbook find the
information where they need it.  Resotring your site wouldn't really be
a FAQ.  A link to instructions for restoring your site would be.
 
In my opinion, a FAQ should not replace the handbook, it should
supplement and provide links and answers for those unable to look up or
find the information in a more appropriate place.  I am willing to be
convinced otherwise.
 
-sp


________________________________

	From: documentation-bounces at drupal.org 
[mailto:documentation-bounces at drupal.org] On Behalf Of Kobus Myburgh
	Sent: Monday, April 24, 2006 6:06 AM
	To: documentation at drupal.org 
	Subject: [documentation] Re: [drupal.org] FAQ
	
	
	Hi,
	 
	I have discussed this on the docs list a while ago, and below is
what I posted. I got some good reaction from puregin, but otherwise no
serious interest. In the meantime, life got ahold of me and I was forced
to retract somewhat from Drupal for some time.
	 
	I am, however, back now, and will create faqs as I sift through
the mailing list archives and forums.
	 
	Since writing the mail shown below, I have created
Administrator's FAQ as well, which received its first post today. The
Contributor's FAQ has two posts in it, with lots of comments, and I want
to reword those, but I want to rephrase it into a Question/Answer
format. Will print it out and do some magic there with the comments and
stuff.
	 
	Basically, here is my plan:
	 
	1. Administrator FAQ
	   -> CRITICAL - Restoring your site
	   -> Open for suggestions about other categories
	2. Contributor FAQ
	   -> I will figure out categories as I scour the list archives
and forums for frequently occuring questions.
	   -> Open for suggestions about other categories
	3. User FAQ (non-admin oriented)
	   -> I will figure out categories as I scour the list archives
and forums for frequently occuring questions.
	   -> Open for suggestions about other categories
	 
	As for Troubleshooting FAQ, I think that should be categorized
under Administrator FAQ, as your typical user won't do troubleshooting.
	 
	Your ideas and comments would be greatly appreciated.
	 
	Regards and thanks,
	 
	Kobus
	 
	=========
	 
	> I couldn't find a suitable FAQ for Drupal users, only one that
was  
	> generally classified as FAQ, and that got me thinking:
	>
	> 1. Rename "FAQ" to "Contributor's FAQ"   [1]
	> 2. Create a new FAQ "User's FAQ"   [2]
	> 3. Maintain both of these FAQ's as the Contributor's FAQ seems
to  
	> be totally unmaintained.
	>
	> I have done #1 and #2 and intend to do #3. I will scourge the

	> mailing lists and forums for questions that are frequently
asked,  
	> and post them there as I identified questions that occurs  
	> frequently enough.
	>
	> If you have any frequent questions to add to these pages,
please  
	> leave them as comments on the "User's FAQ" (as that one is not

	> published and currently considered a working document) but
clearly  
	> mark them as "User" or "Contributor" content.
	>
	> [1] http://drupal.org/node/22567 
	> [2] http://drupal.org/node/44547 
	>
	> Thanks!
	>
	> Kobus
	
	>>> <h.deelstra at gmx.net> 4/24/2006 1:10 PM >>>
	Kobus,
	
	Heine (http://drupal.org/user/17943) has sent you a message via
your
	contact form (http://drupal.org/user/74/contact) at drupal.org.
	
	If you don't want to receive such e-mails, you can change your
settings at
	http://drupal.org/user/74 .
	
	Message:
	
	Hello Kobus,
	
	I noticed the work on FAQs you're doing. I think it's great. Can
you post
	your idea & outline to the docs list or even better, post an
issue? I'm
	sure more people are willing to contribute or think about the
execution.
	
	For example, should the FAQ be a list of questions, each linking
to a page
	which a standard layout (such as you did for the Bad php code)
or should it
	rather be Questions linked to another resource in the handbook.
As an
	example: How to remove 'submitted by' information, directly
linking to the
	relevant page in the Basic site configuration handbook.
	
	Also, what should we do with the Troubleshooting FAQ?
	
	Greets,
	
	Heine