Return-Path: 
 <dev-return-15271-apmail-directory-dev-archive=directory.apache.org@directory.apache.org>
Delivered-To: apmail-directory-dev-archive@www.apache.org
Received: (qmail 27380 invoked from network); 19 Jan 2007 22:19:06 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 19 Jan 2007 22:19:06 -0000
Received: (qmail 37154 invoked by uid 500); 19 Jan 2007 22:19:08 -0000
Delivered-To: apmail-directory-dev-archive@directory.apache.org
Received: (qmail 37127 invoked by uid 500); 19 Jan 2007 22:19:08 -0000
Mailing-List: contact dev-help@directory.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:dev-help@directory.apache.org>
List-Unsubscribe: <mailto:dev-unsubscribe@directory.apache.org>
List-Post: <mailto:dev@directory.apache.org>
List-Id: <dev.directory.apache.org>
Reply-To: "Apache Directory Developers List" <dev@directory.apache.org>
Delivered-To: mailing list dev@directory.apache.org
Received: (qmail 37105 invoked by uid 99); 19 Jan 2007 22:19:07 -0000
Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133)
    by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 19 Jan 2007 14:19:07 -0800
X-ASF-Spam-Status: No, hits=0.0 required=10.0
	tests=
X-Spam-Check-By: apache.org
Received-SPF: pass (herse.apache.org: local policy)
Received: from [209.73.178.206] (HELO web60718.mail.yahoo.com)
 (209.73.178.206)
    by apache.org (qpsmtpd/0.29) with SMTP; Fri, 19 Jan 2007 14:18:58 -0800
Received: (qmail 72055 invoked by uid 60001); 19 Jan 2007 22:18:37 -0000
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
  s=s1024; d=yahoo.com;
  h=X-YMail-OSG:Received:Date:From:Subject:To:In-Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding:Message-ID;
  b=MfLiNzP2ms/VAib4nS9kN6Iwj56NPz8DGJdb+1HeTVKiOwARhuXcMjTKccZPPq/CfsbBmCzHE6pBoBcSyRUOZxbJRoAmPmJAqmPgWaaHJyxs0+FvjfDNZtoRGTPWTAnildWSXW2gpcPMv4TXqY5bwsb3ju+2guN5/Q7tW9HGyNs=;
X-YMail-OSG: 
 _P3cAIcVM1lBlOk8DxgoEwS4Wn31ElFQtp8Yt6lJwRfsUx4dyAzV5KDKcf3k8AfLXlXYJYfVRMk1IRJVzwFhVNkr6eiTBiCFoDs9WQiHZL4f3_1H2lkLoRoqoP1rBmx77Ly2dmVVsvP.2Icy_t_o2idsHSTQDSOcuu3X7ikcxFunr78pQHBOwJ4WwhY9uw--
Received: from [24.13.179.233] by web60718.mail.yahoo.com via HTTP;
 Fri, 19 Jan 2007 14:18:37 PST
Date: Fri, 19 Jan 2007 14:18:37 -0800 (PST)
From: Ole Ersoy <ole_ersoy@yahoo.com>
Subject: Re: svn commit: r497896 -
 /directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt
To: elecharny@iktek.com, directory apache <dev@directory.apache.org>
In-Reply-To: <45B12D56.4070308@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Transfer-Encoding: 8bit
Message-ID: <251523.72044.qm@web60718.mail.yahoo.com>
X-Virus-Checked: Checked by ClamAV on apache.org

Emmanuel,

I took your questions and put them in faq.fml in the
same folder.

I'll paste the document below for those in need of
immidiate satisfaction (I need to run the Maven fml
plugin to produce the html version).

If you put your questions in the same format it makes
a my life a little easier :-)...Only if the questions
are the types you think we probably want to post as
general guidelines for later...

Cheers,
- Ole

<faqs title="Documentation FAQ" toplink="false">
	<part id="1">
		<title>Eclipse Help System</title>

		<faq id="1">
			<question>
				Does the Eclipse Info Center run standalone?
			</question>
			<answer>
				<p>Yes</p>
			</answer>
		</faq>
		<faq id="2">
			<question>What's the process for setting it
up?</question>
			<answer>
				Very straight forward. See:


			
http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/ua_help_setup_infocenter.htm

				We just put it on a server, and point requests at
it
				using Apache's httpd.config configuration file.
			</answer>
		</faq>

		<faq id="3">
			<question>How do we package the
documentation?</question>
			<answer>
				We package documentation as eclipse plugins.
			</answer>
		</faq>

		<faq id="4">
			<question>
				What if someone wants to write documentation in a
non
				html format?
			</question>
			<answer>
				Users and committers can write documentation in
any
				microformat of their choosing, as long as it can
be
				translated into html that has a predefined schema
				template definition.
			</answer>
		</faq>

		<faq id="5">
			<question>
				Do content writers have to write content that
adheres to
				predefined template guidelines?
			</question>
			<answer>Yes.</answer>
		</faq>

		<faq id="6">
			<question>What is a predefined template?</question>
			<answer>
				Something with predefined headings and
instructions for
				the type of content that goes beneath each
heading.
			</answer>
		</faq>

		<faq id="7">
			<question>
				What if a template does not exist that suits the
content
				being written?
			</question>
			<answer>
				A new template can be derived from a current one,
if it
				has commonalities with old templates.

				If the content going into the new template has
heading
				and directions that are exclusive to it alone,
then a
				new template can be defined.
			</answer>
		</faq>
	</part>
</faqs>

 



--- Emmanuel Lecharny <elecharny@gmail.com> wrote:

> Ole Ersoy a �crit :
> 
> >Hey Emmanuel,
> >
> >All those are excellent points.
> >
> >Especially the one about what is the 
> >right system to use and finding agreement.
> >That's what I'm pushing for.  An agreement
> >to use the Eclipse help system for documentation
> >and collaboration within the context of the
> cookbook
> >document in subversion.
> >  
> >
> What I don't get is the scope of this eclipse help
> system, and to what 
> extent we would use it for ADS. AFAIK, this is
> pretty much a tool linked 
> to eclipse ? Do you need to use eclipse in order to
> use read helps? If 
> so, this will be a no go : we have some committers
> (not too much, I 
> admit) who are not using eclipse. The other concern
> I have about it is 
> the kind of doc we might push into this system :
> remember that we have 
> users and also committers who write doco, and it
> could be important to 
> ask them if this tool fit their needs. I don't
> know... Some samples 
> could halp, because I must admit I don't see the
> whole picture. Well, 
> yes, that's it : nothing is better than a clear
> sample :)
> 
> >Just so I understand better, which one of the
> cookbook
> >items would you recommend that I put in JIRA and
> what
> >is the benefit (I understand the things about
> tracking
> >etc. but I'm missing how they apply in this
> context)?
> >  
> >
> In my mind, each cookbook could be a JIRA. For
> instance, let's take one 
> of your cookbook :
> 
> "
> Challenge : Running the eclipse help server.
> 
> Solution
>      See:
>     
>
http://www-128.ibm.com/developerworks/opensource/library/os-eclipsehelp/
> 
> Discussion
>      The Eclipse Help Center runs standalone, with
> an integrated
>      web server.
>      
>      Here's a quick httpd.conf sample borrowed from
> the 
>      above URL on how to forward requests to the
> eclipse help center:     
>
-----------------------------------------------------------------------------
> LoadModule proxy_module
> modules/ApacheModuleProxy.dll
> ProxyPass /eclipsehelprepo
> http://internalhelpserver:8081/help 
> ProxyPassReverse /eclipsehelprepo
> http://internalhelpserver:8081/help
>
-----------------------------------------------------------------------------
> 
> "
> 
> I have created a JIRA for this one : 
> https://issues.apache.org/jira/browse/DIR-201
> 
> It's pretty much the same thing (ok, discussion and
> solution are not 
> exactly explicitly on different places, but as soon
> we have a solution, 
> it should be the last comment before the issue is
> closed.
> 
> wdyt ?
> 
> >As you noted, I'm just sticking with the
> >challenge/solution/discussion format right now
> >because it's a simple template for me to use, that
> I
> >can easily pull information from later.  I also
> think
> >it's a very effective way to focus on something.
> >  
> >
> yeah, I agree and understand. It's better to stick
> to a structure that 
> just writting down some ideas randomly. I just
> wanted to stress out the 
> fact that we may have good tools for that (JIRA,
> Confluence, Mailing 
> List). I don't want to stop you, anyway. I'l just
> trying to figure out 
> what could be the best solution.
> 
> >The ultimate goal with respect to it is to be able
> to
> >have these types of discussions, and have them tied
> >directly to and end deliverable document.
> >
> +1
> 
> >  That way
> >the design rationale and the deliverable document
> are
> >tightly coupled.  Sort of like javadocs and code...
> >  
> >
> Ahhh... Javadoc :) If only every piece of code have
> it's updated Javadoc :)
> 
> >Cheers,
> >- Ole
> >
> >  
> >
> Emmanuel
> 



 
____________________________________________________________________________________
Never miss an email again!
Yahoo! Toolbar alerts you the instant new Mail arrives.
http://tools.search.yahoo.com/toolbar/features/mail/