directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ole Ersoy <>
Subject Re: svn commit: r497896 - /directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt
Date Fri, 19 Jan 2007 22:18:37 GMT

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...

- Ole

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

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

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

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

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

		<faq id="5">
				Do content writers have to write content that
adheres to
				predefined template guidelines?

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

		<faq id="7">
				What if a template does not exist that suits the
				being written?
				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
				and directions that are exclusive to it alone,
then a
				new template can be defined.


--- Emmanuel Lecharny <> 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:
> 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 : 
> 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.

View raw message