You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by oe...@apache.org on 2007/01/19 19:29:25 UTC
svn commit: r497896 -
/directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt
Author: oersoy
Date: Fri Jan 19 10:29:24 2007
New Revision: 497896
URL: http://svn.apache.org/viewvc?view=rev&rev=497896
Log: (empty)
Added:
directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt
Added: directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt
URL: http://svn.apache.org/viewvc/directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt?view=auto&rev=497896
==============================================================================
--- directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt (added)
+++ directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt Fri Jan 19 10:29:24 2007
@@ -0,0 +1,140 @@
+
+
+
+
+
+
+
+
+Challenge
+
+ Understanding the benefits of using the eclipse help system
+ for our documentation effort.
+
+Solution
+
+ TODO Fix later.
+ See:
+ http://directory.apache.org/documentation/collaboration/documentation/benefits
+
+Discussion
+
+ - Simple navigation.
+ - Makes sense with respect to the LDAP Studio eclipse plugin.
+ - Ability to check out, update and resubmit content, structure, and formatting documents.
+ - Separation of content and format
+ - CSS controlled styling.
+ - Separation of content and structure.
+ - XML descriptors for structure documents.
+ - Ability to work on documentation in tool of choice.
+ - Ability to work in personally chosen microformat.
+ - Subversioned documentation.
+ - Quick contribution of individual document to apacheds.
+ - Simplified content management.
+ - Better documentation visibility.
+ - Integrated lucene based searching.
+ - Rapid recreation of documentation in other formats.
+ - One common model for all microformatted documents.
+ - Open source documentation platform for rapid introduction of new documentation capabilities.
+ - Project centric documentation location.
+ - Zero effort with integration of apache documentation into eclipse.
+
+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
+-----------------------------------------------------------------------------
+
+
+Challenge
+
+ Creating an eclipse help system documentation plugin.
+
+Solution
+
+ See:
+ http://www.eclipse.org/articles/Article-Online%20Help%20for%202_0/help1.htm
+ http://www-128.ibm.com/developerworks/opensource/library/os-eclipsehelp/
+
+
+
+
+Challenge
+
+ Creating an eclipse help system plugin manifest file.
+
+Solution
+
+ See:
+ http://www.eclipse.org/articles/Article-Online%20Help%20for%202_0/help1.htm
+ http://www-128.ibm.com/developerworks/opensource/library/os-eclipsehelp/
+
+
+
+
+
+Challenge
+
+ Creating the document table of contents.
+
+Solution
+
+ See:
+ http://www.eclipse.org/articles/Article-Online%20Help%20for%202_0/help1.htm
+ http://www-128.ibm.com/developerworks/opensource/library/os-eclipsehelp/
+
+
+
+
+Challenge
+
+ Choosing a supported microformat.
+
+Solution
+
+ TODO Fix later.
+ See:
+ http://directory.apache.org/microformats
+
+
+
+
+Challenge
+
+ Creating a documentation structure.
+
+
+
+Solution
+
+ See:
+ http://www.eclipse.org/articles/Article-Online%20Help%20for%202_0/help1.htm
+ http://www-128.ibm.com/developerworks/opensource/library/os-eclipsehelp/
+
+
+
+Challenge
+
+
+
+Solution
+
+
+
+
Re: svn commit: r497896 - /directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt
Posted by Ole Ersoy <ol...@yahoo.com>.
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.
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)?
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.
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. That way
the design rationale and the deliverable document are
tightly coupled. Sort of like javadocs and code...
Cheers,
- Ole
--- Emmanuel Lecharny <el...@gmail.com> wrote:
> Hi Ole,
>
> looking at your first commits (welcome in the
> pleasure dome :), I'm just
> wondering if the Challenge/Solution/discussion
> wouldn't be better filled as
> JIRA's ?
>
> In my mind, JIRA is not only for bugs, but also a
> very good tools to submit
> Features, Tasks, Improvments and Wishes (all such
> categories which describe
> very clearly what you intend to do when so called
> 'challenge' is pretty much
> a catch all)
>
> You can also trace the status (is it inprogress,
> closed, etc) and you can
> event add some comments and describe the solution.
> Even commits of code can
> be automatically linked to JIRA if you add the JIRA
> number in the commit''s
> comment.
>
> We have great tools, what about using them?
>
> Of course, if you think that JIRA, for a reason or
> another does not fit your
> need, we can discuss this point further. (there is
> no silver bullet ...)
>
> The point I want to raise is that, as a team, we try
> to collaborate as much
> as possible. We do it through tools (JIRA, ML,
> Confluence, Maven, Subversion
> ...). We can define and use new tools, but the best
> thing would be to find a
> kind of agreement around them: keep in mind that you
> should not be the only
> one working with your own tools : this is not "the
> Apache way" (tm).
>
> No offense at all, I'm just trying to check if I
> have missed something about
> these 'challenge' things :)
>
>
> --
> Cordialement,
> Emmanuel Lécharny
> www.iktek.com
>
____________________________________________________________________________________
Food fight? Enjoy some healthy debate
in the Yahoo! Answers Food & Drink Q&A.
http://answers.yahoo.com/dir/?link=list&sid=396545367
Re: svn commit: r497896 - /directory/sandbox/oersoy/collaboration.platform.documentation/cookbook.apt
Posted by Emmanuel Lecharny <el...@gmail.com>.
Hi Ole,
looking at your first commits (welcome in the pleasure dome :), I'm just
wondering if the Challenge/Solution/discussion wouldn't be better filled as
JIRA's ?
In my mind, JIRA is not only for bugs, but also a very good tools to submit
Features, Tasks, Improvments and Wishes (all such categories which describe
very clearly what you intend to do when so called 'challenge' is pretty much
a catch all)
You can also trace the status (is it inprogress, closed, etc) and you can
event add some comments and describe the solution. Even commits of code can
be automatically linked to JIRA if you add the JIRA number in the commit''s
comment.
We have great tools, what about using them?
Of course, if you think that JIRA, for a reason or another does not fit your
need, we can discuss this point further. (there is no silver bullet ...)
The point I want to raise is that, as a team, we try to collaborate as much
as possible. We do it through tools (JIRA, ML, Confluence, Maven, Subversion
...). We can define and use new tools, but the best thing would be to find a
kind of agreement around them: keep in mind that you should not be the only
one working with your own tools : this is not "the Apache way" (tm).
No offense at all, I'm just trying to check if I have missed something about
these 'challenge' things :)
--
Cordialement,
Emmanuel Lécharny
www.iktek.com