Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Archived » ORMF » Re: Documentation components
Re: Documentation components [message #7666] Wed, 26 March 2008 11:39 Go to next message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-03-26 03:10:56 +0000, donald.g.dunne@boeing.com (Don Dunne) said:

> I believe the original comment was in the are of documenting OSEE. I
> would imagine a few different levels of documentation.
> One that is of immediate interest is the documentation of the
> architecture and API so we can get our interested parties up and
> running as fast as possible. We are planning on holding a WebEx soon
> to walk through the architecture of OSEE for anyone interested. We
> could then split into our different areas of interest and provide for a
> deeper dive for those involved.
>
> Another area is is for the users of OSEE that includes expanding the
> help sections for the provided OSEE perspectives, views and editors. I
> believe we have a good start on this, but there are probably persons
> with a much better ability to create a good set of user help.

Don,

Thanks for the reply.

I do not think we would be very suited for the documentation of the
OSEE system under the covers, as we know very little about it. However
we would be happy in participating in the user help effort for the
areas that we will get familiar with as part of our integration (and of
our daily usage of OSEE... :-).

Cheerio,
B.

--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #7729 is a reply to message #7666] Wed, 26 March 2008 21:19 Go to previous messageGo to next message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
That would be great. Would this be an area that you would want to get
started on or handle as you go? I would be happy to help familiarize you
with the current help documentation so that you could read and understand
what is there and maybe enhance as you go? Let me know.
Re: Documentation components [message #7750 is a reply to message #7729] Thu, 27 March 2008 08:38 Go to previous messageGo to next message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-03-27 01:19:47 +0000, donald.g.dunne@boeing.com (Don Dunne) said:

> That would be great. Would this be an area that you would want to get
> started on or handle as you go? I would be happy to help familiarize
> you with the current help documentation so that you could read and
> understand what is there and maybe enhance as you go? Let me know.

It would definitely be very useful for me/us to get familiar with the
documentation as a first step. Let me know how you want to proceed with
this.

Thanks,
B.

--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #7771 is a reply to message #7750] Thu, 27 March 2008 13:20 Go to previous messageGo to next message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
OSEE's documentation is provided through the standard eclipse help
extension points. The first step, if you haven't already, would be to
become familiar with how Eclipse provides these extensions. The article
http://www.eclipse.org/articles/Article-Online%20Help%20for% 202_0/help1.htm
should be a good place to start.

After that, you will need to create a workspace and checkout our plugins
from eclipse.org/osee. I think Joel has made some good progress on this.
We have tried to use a standard mechanism of creating a "reference" folder
in the plugins that contribute help. This keeps the help files separate
from other files in the plugins.

A good example is in org.eclipse.osee.framework.ui.skynet/reference.

The toc.xml is the main table of contents file that references other xml
and html files.

There is also a contexts.xml file that defines the ids that the code uses
for the context sensitive help when the user selects "F1". the
contexts.xml in this plugin specifies a context id="mass_artifact_editor".
If you look in the file MassArtifactEditor.java, you will see a line
SkynetGuiPlugin.getInstance().setHelp(getContainer(),
"mass_artifact_editor");
that calls out that id. This maps the editor with that help location.

This should help get you started. Let me know as questions arise.
Re: Documentation components [message #7897 is a reply to message #7771] Sat, 29 March 2008 09:43 Go to previous messageGo to next message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-03-27 17:20:35 +0000, donald.g.dunne@boeing.com (Don Dunne) said:

> OSEE's documentation is provided through the standard eclipse help
> extension points. The first step, if you haven't already, would be to
> become familiar with how Eclipse provides these extensions. The
> article
> http://www.eclipse.org/articles/Article-Online%20Help%20for% 202_0/help1.htm
> should be a good place to start.
>
> After that, you will need to create a workspace and checkout our
> plugins from eclipse.org/osee. I think Joel has made some good
> progress on this. We have tried to use a standard mechanism of
> creating a "reference" folder in the plugins that contribute help.
> This keeps the help files separate from other files in the plugins.
>
> A good example is in org.eclipse.osee.framework.ui.skynet/reference.
>
> The toc.xml is the main table of contents file that references other
> xml and html files.
> There is also a contexts.xml file that defines the ids that the code
> uses for the context sensitive help when the user selects "F1". the
> contexts.xml in this plugin specifies a context
> id="mass_artifact_editor". If you look in the file
> MassArtifactEditor.java, you will see a line
> SkynetGuiPlugin.getInstance().setHelp(getContainer(),
> "mass_artifact_editor");
> that calls out that id. This maps the editor with that help location.
>
> This should help get you started. Let me know as questions arise.


Hi Don.

Thanks for the explanation. In actual fact I shuld have been clearer in
my reply. I do know the mechanics of contributing help (I have done it
for Useme/ORMF). I assumed that your offer of help was geared towards
steering me in the "optimal" way to read the content of the OSEE help.
Never mind, I am sorry I wasted some of your time typing away.

In any case, I will pore over the documentation soon and take it from there.

I just have one point to make. I notice from your post that you
contribute help from a package within each plugin. I suggest that this
approach works well if only one team is contributing help, but it
causes unecessary dependencies and problems when the peole who
contribute help are different from those that develop the plugin. To
quote an authoritative source, from the Eclipse Corner article entitled
"Contributing a little help":

"You can either contribute the online help as part of your code plug-in
or provide it separately in its own documentation plug-in. This
separation is beneficial in those situations where the code and
documentation teams are different groups or where you want to reduce
the coupling/dependency between the documentation and code."

If you agree with this, I would be happy to take on board the job of
migrating your help to standalone plugins. I am comfortable with that.
I could then submit the help plugins as patches or as a proper
contribution, depending upon where we are with ORMF's proposal. Let me
know.

Cheerio,
B.

--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #7917 is a reply to message #7897] Sat, 29 March 2008 14:48 Go to previous messageGo to next message
Joel Rosi-Schwartz is currently offline Joel Rosi-Schwartz
Messages: 624
Registered: July 2009
Location: London. England
Senior Member
On 2008-03-29 13:43:38 +0000, Barbara Rosi-Schwartz
<Barbara.Rosi-Schwartz@Etish.org> said:

> I just have one point to make. I notice from your post that you
> contribute help from a package within each plugin. I suggest that this
> approach works well if only one team is contributing help, but it
> causes unecessary dependencies and problems when the peole who
> contribute help are different from those that develop the plugin. To
> quote an authoritative source, from the Eclipse Corner article entitled
> "Contributing a little help":
>
> "You can either contribute the online help as part of your code plug-in
> or provide it separately in its own documentation plug-in. This
> separation is beneficial in those situations where the code and
> documentation teams are different groups or where you want to reduce
> the coupling/dependency between the documentation and code."

There is another driver for separating them. If the help is part of the
code plug-in it can only be viewed be someone who has successfully
built and deployed the application and fulfilled all of its
dependencies; a non-trivial task. If they are separate documentation
plug-ins you remove all dependencies to the application. Any interested
party can easily download the documentation plug-ins, install them and
view the help to get a feel for OSEE. This lowers the hurdle
significantly for all the folks (the majority) who are curious for more
details, but not comfortable with building and installing the whole
applications. Even after we have a binary release, it still makes it
very simple to provide a documentation target on the update site for
folks who want a easy and progressive adoption path.

Joel
--
Joel Rosi-Schwartz
Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^...^
/ o,o \ The proud parents of Useme
|) ::: (| The Open Requirements Management Tool
====w=w==== [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #8941 is a reply to message #7917] Mon, 31 March 2008 13:21 Go to previous messageGo to next message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
Joel Rosi-Schwartz wrote:
> On 2008-03-29 13:43:38 +0000, Barbara Rosi-Schwartz
> <Barbara.Rosi-Schwartz@Etish.org> said:
>
>> I just have one point to make. I notice from your post that you
>> contribute help from a package within each plugin. I suggest that this
>> approach works well if only one team is contributing help, but it
>> causes unecessary dependencies and problems when the peole who
>> contribute help are different from those that develop the plugin. To
>> quote an authoritative source, from the Eclipse Corner article
>> entitled "Contributing a little help":
>>
>> "You can either contribute the online help as part of your code
>> plug-in or provide it separately in its own documentation plug-in.
>> This separation is beneficial in those situations where the code and
>> documentation teams are different groups or where you want to reduce
>> the coupling/dependency between the documentation and code."
>
> There is another driver for separating them. If the help is part of the
> code plug-in it can only be viewed be someone who has successfully built
> and deployed the application and fulfilled all of its dependencies; a
> non-trivial task. If they are separate documentation plug-ins you remove
> all dependencies to the application. Any interested party can easily
> download the documentation plug-ins, install them and view the help to
> get a feel for OSEE. This lowers the hurdle significantly for all the
> folks (the majority) who are curious for more details, but not
> comfortable with building and installing the whole applications. Even
> after we have a binary release, it still makes it very simple to provide
> a documentation target on the update site for folks who want a easy and
> progressive adoption path.
>
> Joel

Certainly great points for deploying in a single plugin. We actually
started that way and decided to separate it out. The driving force was
that we intend to allow deployment of OSEE without certain
functionality. eg. You could deploy OSEE without ATS or Define. With
the help in a single plugin, the workbench help would show help for
functionality that didn't exist in the deployment. I think the single
plugin would work if we provided an all-or-nothing application.
Re: Documentation components [message #8961 is a reply to message #8941] Mon, 31 March 2008 13:29 Go to previous messageGo to next message
Joel Rosi-Schwartz is currently offline Joel Rosi-Schwartz
Messages: 624
Registered: July 2009
Location: London. England
Senior Member
On 2008-03-31 18:21:57 +0100, Don Dunne <donald.g.dunne@boeing.com> said:

> Joel Rosi-Schwartz wrote:
>> On 2008-03-29 13:43:38 +0000, Barbara Rosi-Schwartz
>> <Barbara.Rosi-Schwartz@Etish.org> said:
>>
>>> I just have one point to make. I notice from your post that you
>>> contribute help from a package within each plugin. I suggest that this
>>> approach works well if only one team is contributing help, but it
>>> causes unecessary dependencies and problems when the peole who
>>> contribute help are different from those that develop the plugin. To
>>> quote an authoritative source, from the Eclipse Corner article entitled
>>> "Contributing a little help":
>>>
>>> "You can either contribute the online help as part of your code plug-in
>>> or provide it separately in its own documentation plug-in. This
>>> separation is beneficial in those situations where the code and
>>> documentation teams are different groups or where you want to reduce
>>> the coupling/dependency between the documentation and code."
>>
>> There is another driver for separating them. If the help is part of the
>> code plug-in it can only be viewed be someone who has successfully
>> built and deployed the application and fulfilled all of its
>> dependencies; a non-trivial task. If they are separate documentation
>> plug-ins you remove all dependencies to the application. Any interested
>> party can easily download the documentation plug-ins, install them and
>> view the help to get a feel for OSEE. This lowers the hurdle
>> significantly for all the folks (the majority) who are curious for more
>> details, but not comfortable with building and installing the whole
>> applications. Even after we have a binary release, it still makes it
>> very simple to provide a documentation target on the update site for
>> folks who want a easy and progressive adoption path.
>>
>> Joel
>
> Certainly great points for deploying in a single plugin. We actually
> started that way and decided to separate it out. The driving force was
> that we intend to allow deployment of OSEE without certain
> functionality. eg. You could deploy OSEE without ATS or Define. With
> the help in a single plugin, the workbench help would show help for
> functionality that didn't exist in the deployment. I think the single
> plugin would work if we provided an all-or-nothing application.

The other strategy, and the one we have used on Useme to date, is to
provide a help bundle for each "meaningful" plug. For example in the
OSEE case this could map to a help bundle for say OSEE base (general
background and principles), Define, ATS, etc. Each bundle can still
reference common help such as base. This keeps it all clean and modular.

Joel
--
Joel Rosi-Schwartz
Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^...^
/ o,o \ The proud parents of Useme
|) ::: (| The Open Requirements Management Tool
====w=w==== [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #8981 is a reply to message #8961] Tue, 01 April 2008 14:13 Go to previous messageGo to next message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
Joel Rosi-Schwartz wrote:
>
> The other strategy, and the one we have used on Useme to date, is to
> provide a help bundle for each "meaningful" plug. For example in the
> OSEE case this could map to a help bundle for say OSEE base (general
> background and principles), Define, ATS, etc. Each bundle can still
> reference common help such as base. This keeps it all clean and modular.
>
> Joel

Great solution. We talked to the other contributors this morning and
agreed to move in this direction with the help files. We would love
your help, Barbara, if this is something you're willing to take on.

Here's our recommendation for the doc plugins

org.eclipse.osee.framework.ui.feature.doc
org.eclipse.osee.framework.feature.doc
org.eclipse.osee.define.feature.doc
org.eclipse.osee.ats.feature.doc
Re: Documentation components [message #9023 is a reply to message #8981] Tue, 01 April 2008 14:27 Go to previous messageGo to next message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-04-01 19:13:55 +0100, Don Dunne <donald.g.dunne@boeing.com> said:

>
> Great solution. We talked to the other contributors this morning and
> agreed to move in this direction with the help files. We would love
> your help, Barbara, if this is something you're willing to take on.
>
> Here's our recommendation for the doc plugins
>
> org.eclipse.osee.framework.ui.feature.doc
> org.eclipse.osee.framework.feature.doc
> org.eclipse.osee.define.feature.doc
> org.eclipse.osee.ats.feature.doc


Yup, I would be delighted to do it. This is all under the assumption
that nothing is terribly urgent on your part: we do have quite a lot on
our plate right now, so it may be 5 to 6 weeks until I complete the
task. However, if this is not a problem for you guys, I am more than
happy to take on the responsibility.

Cheerio,
B.
--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #9064 is a reply to message #9023] Tue, 01 April 2008 15:25 Go to previous messageGo to next message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
Barbara Rosi-Schwartz wrote:
> On 2008-04-01 19:13:55 +0100, Don Dunne <donald.g.dunne@boeing.com> said:
>
>>
>> Great solution. We talked to the other contributors this morning and
>> agreed to move in this direction with the help files. We would love
>> your help, Barbara, if this is something you're willing to take on.
>>
>> Here's our recommendation for the doc plugins
>>
>> org.eclipse.osee.framework.ui.feature.doc
>> org.eclipse.osee.framework.feature.doc
>> org.eclipse.osee.define.feature.doc
>> org.eclipse.osee.ats.feature.doc
>
>
> Yup, I would be delighted to do it. This is all under the assumption
> that nothing is terribly urgent on your part: we do have quite a lot on
> our plate right now, so it may be 5 to 6 weeks until I complete the
> task. However, if this is not a problem for you guys, I am more than
> happy to take on the responsibility.
>
> Cheerio,
> B.

Not a problem at all. Maybe splitting the task in to smaller pieces
would make it easier to manage the commits so we don't get the plugins
too far out of date with what your working on.
Re: Documentation components [message #9085 is a reply to message #9064] Wed, 02 April 2008 12:02 Go to previous messageGo to next message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-04-01 20:25:31 +0100, Don Dunne <donald.g.dunne@boeing.com> said:

> Barbara Rosi-Schwartz wrote:
>> On 2008-04-01 19:13:55 +0100, Don Dunne <donald.g.dunne@boeing.com> said:
>>
>>>
>>> Great solution. We talked to the other contributors this morning and
>>> agreed to move in this direction with the help files. We would love
>>> your help, Barbara, if this is something you're willing to take on.
>>>
>>> Here's our recommendation for the doc plugins
>>>
>>> org.eclipse.osee.framework.ui.feature.doc
>>> org.eclipse.osee.framework.feature.doc
>>> org.eclipse.osee.define.feature.doc
>>> org.eclipse.osee.ats.feature.doc
>>
>>
>> Yup, I would be delighted to do it. This is all under the assumption
>> that nothing is terribly urgent on your part: we do have quite a lot on
>> our plate right now, so it may be 5 to 6 weeks until I complete the
>> task. However, if this is not a problem for you guys, I am more than
>> happy to take on the responsibility.
>>
>> Cheerio,
>> B.
>
> Not a problem at all. Maybe splitting the task in to smaller pieces
> would make it easier to manage the commits so we don't get the plugins
> too far out of date with what your working on.

Very sensible approach, Don, thanks.
B.

--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
Blog: http//www.brs4etish.blogspot.com
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #10726 is a reply to message #9023] Wed, 14 May 2008 08:20 Go to previous message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-04-01 19:27:14 +0100, Barbara Rosi-Schwartz
<Barbara.Rosi-Schwartz@Etish.org> said:

> On 2008-04-01 19:13:55 +0100, Don Dunne <donald.g.dunne@boeing.com> said:
>
>>
>> Great solution. We talked to the other contributors this morning and
>> agreed to move in this direction with the help files. We would love
>> your help, Barbara, if this is something you're willing to take on.
>>
>> Here's our recommendation for the doc plugins
>>
>> org.eclipse.osee.framework.ui.feature.doc
>> org.eclipse.osee.framework.feature.doc
>> org.eclipse.osee.define.feature.doc
>> org.eclipse.osee.ats.feature.doc
>
>
> Yup, I would be delighted to do it. This is all under the assumption
> that nothing is terribly urgent on your part: we do have quite a lot on
> our plate right now, so it may be 5 to 6 weeks until I complete the
> task. However, if this is not a problem for you guys, I am more than
> happy to take on the responsibility.
>
> Cheerio,
> B.

Hello Don et al.

Unfortunately, due to the limited amount of resources for open source
related work that we are experiencing and of which we have widely
talked about in the last week or so, I am forced to decline my previous
offer of help with your help (pun intended).

I apologise about this, I always do my best to make good on my offers
and not to let people down, but at the moment I cannot possibly attend
to this task, there are simply not enough hours in the day :-(

I hope this does not upset your plans too drastically and I aplogise
for any inconvenience I may cause.

Kindest regards,
B.
--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
Blog: http://www.brs4etish.blogspot.com
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #562578 is a reply to message #7666] Wed, 26 March 2008 21:19 Go to previous message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
That would be great. Would this be an area that you would want to get
started on or handle as you go? I would be happy to help familiarize you
with the current help documentation so that you could read and understand
what is there and maybe enhance as you go? Let me know.
Re: Documentation components [message #562601 is a reply to message #7729] Thu, 27 March 2008 08:38 Go to previous message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-03-27 01:19:47 +0000, donald.g.dunne@boeing.com (Don Dunne) said:

> That would be great. Would this be an area that you would want to get
> started on or handle as you go? I would be happy to help familiarize
> you with the current help documentation so that you could read and
> understand what is there and maybe enhance as you go? Let me know.

It would definitely be very useful for me/us to get familiar with the
documentation as a first step. Let me know how you want to proceed with
this.

Thanks,
B.

--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #562626 is a reply to message #7750] Thu, 27 March 2008 13:20 Go to previous message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
OSEE's documentation is provided through the standard eclipse help
extension points. The first step, if you haven't already, would be to
become familiar with how Eclipse provides these extensions. The article
http://www.eclipse.org/articles/Article-Online%20Help%20for% 202_0/help1.htm
should be a good place to start.

After that, you will need to create a workspace and checkout our plugins
from eclipse.org/osee. I think Joel has made some good progress on this.
We have tried to use a standard mechanism of creating a "reference" folder
in the plugins that contribute help. This keeps the help files separate
from other files in the plugins.

A good example is in org.eclipse.osee.framework.ui.skynet/reference.

The toc.xml is the main table of contents file that references other xml
and html files.

There is also a contexts.xml file that defines the ids that the code uses
for the context sensitive help when the user selects "F1". the
contexts.xml in this plugin specifies a context id="mass_artifact_editor".
If you look in the file MassArtifactEditor.java, you will see a line
SkynetGuiPlugin.getInstance().setHelp(getContainer(),
"mass_artifact_editor");
that calls out that id. This maps the editor with that help location.

This should help get you started. Let me know as questions arise.
Re: Documentation components [message #562769 is a reply to message #7771] Sat, 29 March 2008 09:43 Go to previous message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-03-27 17:20:35 +0000, donald.g.dunne@boeing.com (Don Dunne) said:

> OSEE's documentation is provided through the standard eclipse help
> extension points. The first step, if you haven't already, would be to
> become familiar with how Eclipse provides these extensions. The
> article
> http://www.eclipse.org/articles/Article-Online%20Help%20for% 202_0/help1.htm
> should be a good place to start.
>
> After that, you will need to create a workspace and checkout our
> plugins from eclipse.org/osee. I think Joel has made some good
> progress on this. We have tried to use a standard mechanism of
> creating a "reference" folder in the plugins that contribute help.
> This keeps the help files separate from other files in the plugins.
>
> A good example is in org.eclipse.osee.framework.ui.skynet/reference.
>
> The toc.xml is the main table of contents file that references other
> xml and html files.
> There is also a contexts.xml file that defines the ids that the code
> uses for the context sensitive help when the user selects "F1". the
> contexts.xml in this plugin specifies a context
> id="mass_artifact_editor". If you look in the file
> MassArtifactEditor.java, you will see a line
> SkynetGuiPlugin.getInstance().setHelp(getContainer(),
> "mass_artifact_editor");
> that calls out that id. This maps the editor with that help location.
>
> This should help get you started. Let me know as questions arise.


Hi Don.

Thanks for the explanation. In actual fact I shuld have been clearer in
my reply. I do know the mechanics of contributing help (I have done it
for Useme/ORMF). I assumed that your offer of help was geared towards
steering me in the "optimal" way to read the content of the OSEE help.
Never mind, I am sorry I wasted some of your time typing away.

In any case, I will pore over the documentation soon and take it from there.

I just have one point to make. I notice from your post that you
contribute help from a package within each plugin. I suggest that this
approach works well if only one team is contributing help, but it
causes unecessary dependencies and problems when the peole who
contribute help are different from those that develop the plugin. To
quote an authoritative source, from the Eclipse Corner article entitled
"Contributing a little help":

"You can either contribute the online help as part of your code plug-in
or provide it separately in its own documentation plug-in. This
separation is beneficial in those situations where the code and
documentation teams are different groups or where you want to reduce
the coupling/dependency between the documentation and code."

If you agree with this, I would be happy to take on board the job of
migrating your help to standalone plugins. I am comfortable with that.
I could then submit the help plugins as patches or as a proper
contribution, depending upon where we are with ORMF's proposal. Let me
know.

Cheerio,
B.

--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #562793 is a reply to message #7897] Sat, 29 March 2008 14:48 Go to previous message
Joel Rosi-Schwartz is currently offline Joel Rosi-Schwartz
Messages: 624
Registered: July 2009
Location: London. England
Senior Member
On 2008-03-29 13:43:38 +0000, Barbara Rosi-Schwartz
<Barbara.Rosi-Schwartz@Etish.org> said:

> I just have one point to make. I notice from your post that you
> contribute help from a package within each plugin. I suggest that this
> approach works well if only one team is contributing help, but it
> causes unecessary dependencies and problems when the peole who
> contribute help are different from those that develop the plugin. To
> quote an authoritative source, from the Eclipse Corner article entitled
> "Contributing a little help":
>
> "You can either contribute the online help as part of your code plug-in
> or provide it separately in its own documentation plug-in. This
> separation is beneficial in those situations where the code and
> documentation teams are different groups or where you want to reduce
> the coupling/dependency between the documentation and code."

There is another driver for separating them. If the help is part of the
code plug-in it can only be viewed be someone who has successfully
built and deployed the application and fulfilled all of its
dependencies; a non-trivial task. If they are separate documentation
plug-ins you remove all dependencies to the application. Any interested
party can easily download the documentation plug-ins, install them and
view the help to get a feel for OSEE. This lowers the hurdle
significantly for all the folks (the majority) who are curious for more
details, but not comfortable with building and installing the whole
applications. Even after we have a binary release, it still makes it
very simple to provide a documentation target on the update site for
folks who want a easy and progressive adoption path.

Joel
--
Joel Rosi-Schwartz
Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^...^
/ o,o \ The proud parents of Useme
|) ::: (| The Open Requirements Management Tool
====w=w==== [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #562949 is a reply to message #7917] Mon, 31 March 2008 13:21 Go to previous message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
Joel Rosi-Schwartz wrote:
> On 2008-03-29 13:43:38 +0000, Barbara Rosi-Schwartz
> <Barbara.Rosi-Schwartz@Etish.org> said:
>
>> I just have one point to make. I notice from your post that you
>> contribute help from a package within each plugin. I suggest that this
>> approach works well if only one team is contributing help, but it
>> causes unecessary dependencies and problems when the peole who
>> contribute help are different from those that develop the plugin. To
>> quote an authoritative source, from the Eclipse Corner article
>> entitled "Contributing a little help":
>>
>> "You can either contribute the online help as part of your code
>> plug-in or provide it separately in its own documentation plug-in.
>> This separation is beneficial in those situations where the code and
>> documentation teams are different groups or where you want to reduce
>> the coupling/dependency between the documentation and code."
>
> There is another driver for separating them. If the help is part of the
> code plug-in it can only be viewed be someone who has successfully built
> and deployed the application and fulfilled all of its dependencies; a
> non-trivial task. If they are separate documentation plug-ins you remove
> all dependencies to the application. Any interested party can easily
> download the documentation plug-ins, install them and view the help to
> get a feel for OSEE. This lowers the hurdle significantly for all the
> folks (the majority) who are curious for more details, but not
> comfortable with building and installing the whole applications. Even
> after we have a binary release, it still makes it very simple to provide
> a documentation target on the update site for folks who want a easy and
> progressive adoption path.
>
> Joel

Certainly great points for deploying in a single plugin. We actually
started that way and decided to separate it out. The driving force was
that we intend to allow deployment of OSEE without certain
functionality. eg. You could deploy OSEE without ATS or Define. With
the help in a single plugin, the workbench help would show help for
functionality that didn't exist in the deployment. I think the single
plugin would work if we provided an all-or-nothing application.
Re: Documentation components [message #562972 is a reply to message #8941] Mon, 31 March 2008 13:29 Go to previous message
Joel Rosi-Schwartz is currently offline Joel Rosi-Schwartz
Messages: 624
Registered: July 2009
Location: London. England
Senior Member
On 2008-03-31 18:21:57 +0100, Don Dunne <donald.g.dunne@boeing.com> said:

> Joel Rosi-Schwartz wrote:
>> On 2008-03-29 13:43:38 +0000, Barbara Rosi-Schwartz
>> <Barbara.Rosi-Schwartz@Etish.org> said:
>>
>>> I just have one point to make. I notice from your post that you
>>> contribute help from a package within each plugin. I suggest that this
>>> approach works well if only one team is contributing help, but it
>>> causes unecessary dependencies and problems when the peole who
>>> contribute help are different from those that develop the plugin. To
>>> quote an authoritative source, from the Eclipse Corner article entitled
>>> "Contributing a little help":
>>>
>>> "You can either contribute the online help as part of your code plug-in
>>> or provide it separately in its own documentation plug-in. This
>>> separation is beneficial in those situations where the code and
>>> documentation teams are different groups or where you want to reduce
>>> the coupling/dependency between the documentation and code."
>>
>> There is another driver for separating them. If the help is part of the
>> code plug-in it can only be viewed be someone who has successfully
>> built and deployed the application and fulfilled all of its
>> dependencies; a non-trivial task. If they are separate documentation
>> plug-ins you remove all dependencies to the application. Any interested
>> party can easily download the documentation plug-ins, install them and
>> view the help to get a feel for OSEE. This lowers the hurdle
>> significantly for all the folks (the majority) who are curious for more
>> details, but not comfortable with building and installing the whole
>> applications. Even after we have a binary release, it still makes it
>> very simple to provide a documentation target on the update site for
>> folks who want a easy and progressive adoption path.
>>
>> Joel
>
> Certainly great points for deploying in a single plugin. We actually
> started that way and decided to separate it out. The driving force was
> that we intend to allow deployment of OSEE without certain
> functionality. eg. You could deploy OSEE without ATS or Define. With
> the help in a single plugin, the workbench help would show help for
> functionality that didn't exist in the deployment. I think the single
> plugin would work if we provided an all-or-nothing application.

The other strategy, and the one we have used on Useme to date, is to
provide a help bundle for each "meaningful" plug. For example in the
OSEE case this could map to a help bundle for say OSEE base (general
background and principles), Define, ATS, etc. Each bundle can still
reference common help such as base. This keeps it all clean and modular.

Joel
--
Joel Rosi-Schwartz
Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^...^
/ o,o \ The proud parents of Useme
|) ::: (| The Open Requirements Management Tool
====w=w==== [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #562996 is a reply to message #8961] Tue, 01 April 2008 14:13 Go to previous message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
Joel Rosi-Schwartz wrote:
>
> The other strategy, and the one we have used on Useme to date, is to
> provide a help bundle for each "meaningful" plug. For example in the
> OSEE case this could map to a help bundle for say OSEE base (general
> background and principles), Define, ATS, etc. Each bundle can still
> reference common help such as base. This keeps it all clean and modular.
>
> Joel

Great solution. We talked to the other contributors this morning and
agreed to move in this direction with the help files. We would love
your help, Barbara, if this is something you're willing to take on.

Here's our recommendation for the doc plugins

org.eclipse.osee.framework.ui.feature.doc
org.eclipse.osee.framework.feature.doc
org.eclipse.osee.define.feature.doc
org.eclipse.osee.ats.feature.doc
Re: Documentation components [message #563041 is a reply to message #8981] Tue, 01 April 2008 14:27 Go to previous message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-04-01 19:13:55 +0100, Don Dunne <donald.g.dunne@boeing.com> said:

>
> Great solution. We talked to the other contributors this morning and
> agreed to move in this direction with the help files. We would love
> your help, Barbara, if this is something you're willing to take on.
>
> Here's our recommendation for the doc plugins
>
> org.eclipse.osee.framework.ui.feature.doc
> org.eclipse.osee.framework.feature.doc
> org.eclipse.osee.define.feature.doc
> org.eclipse.osee.ats.feature.doc


Yup, I would be delighted to do it. This is all under the assumption
that nothing is terribly urgent on your part: we do have quite a lot on
our plate right now, so it may be 5 to 6 weeks until I complete the
task. However, if this is not a problem for you guys, I am more than
happy to take on the responsibility.

Cheerio,
B.
--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #563087 is a reply to message #9023] Tue, 01 April 2008 15:25 Go to previous message
Donald Dunne is currently offline Donald Dunne
Messages: 191
Registered: July 2009
Senior Member
Barbara Rosi-Schwartz wrote:
> On 2008-04-01 19:13:55 +0100, Don Dunne <donald.g.dunne@boeing.com> said:
>
>>
>> Great solution. We talked to the other contributors this morning and
>> agreed to move in this direction with the help files. We would love
>> your help, Barbara, if this is something you're willing to take on.
>>
>> Here's our recommendation for the doc plugins
>>
>> org.eclipse.osee.framework.ui.feature.doc
>> org.eclipse.osee.framework.feature.doc
>> org.eclipse.osee.define.feature.doc
>> org.eclipse.osee.ats.feature.doc
>
>
> Yup, I would be delighted to do it. This is all under the assumption
> that nothing is terribly urgent on your part: we do have quite a lot on
> our plate right now, so it may be 5 to 6 weeks until I complete the
> task. However, if this is not a problem for you guys, I am more than
> happy to take on the responsibility.
>
> Cheerio,
> B.

Not a problem at all. Maybe splitting the task in to smaller pieces
would make it easier to manage the commits so we don't get the plugins
too far out of date with what your working on.
Re: Documentation components [message #563113 is a reply to message #9064] Wed, 02 April 2008 12:02 Go to previous message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-04-01 20:25:31 +0100, Don Dunne <donald.g.dunne@boeing.com> said:

> Barbara Rosi-Schwartz wrote:
>> On 2008-04-01 19:13:55 +0100, Don Dunne <donald.g.dunne@boeing.com> said:
>>
>>>
>>> Great solution. We talked to the other contributors this morning and
>>> agreed to move in this direction with the help files. We would love
>>> your help, Barbara, if this is something you're willing to take on.
>>>
>>> Here's our recommendation for the doc plugins
>>>
>>> org.eclipse.osee.framework.ui.feature.doc
>>> org.eclipse.osee.framework.feature.doc
>>> org.eclipse.osee.define.feature.doc
>>> org.eclipse.osee.ats.feature.doc
>>
>>
>> Yup, I would be delighted to do it. This is all under the assumption
>> that nothing is terribly urgent on your part: we do have quite a lot on
>> our plate right now, so it may be 5 to 6 weeks until I complete the
>> task. However, if this is not a problem for you guys, I am more than
>> happy to take on the responsibility.
>>
>> Cheerio,
>> B.
>
> Not a problem at all. Maybe splitting the task in to smaller pieces
> would make it easier to manage the commits so we don't get the plugins
> too far out of date with what your working on.

Very sensible approach, Don, thanks.
B.

--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
Blog: http//www.brs4etish.blogspot.com
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Documentation components [message #563754 is a reply to message #9023] Wed, 14 May 2008 08:20 Go to previous message
Barbara Rosi-Schwartz is currently offline Barbara Rosi-Schwartz
Messages: 448
Registered: July 2009
Senior Member
On 2008-04-01 19:27:14 +0100, Barbara Rosi-Schwartz
<Barbara.Rosi-Schwartz@Etish.org> said:

> On 2008-04-01 19:13:55 +0100, Don Dunne <donald.g.dunne@boeing.com> said:
>
>>
>> Great solution. We talked to the other contributors this morning and
>> agreed to move in this direction with the help files. We would love
>> your help, Barbara, if this is something you're willing to take on.
>>
>> Here's our recommendation for the doc plugins
>>
>> org.eclipse.osee.framework.ui.feature.doc
>> org.eclipse.osee.framework.feature.doc
>> org.eclipse.osee.define.feature.doc
>> org.eclipse.osee.ats.feature.doc
>
>
> Yup, I would be delighted to do it. This is all under the assumption
> that nothing is terribly urgent on your part: we do have quite a lot on
> our plate right now, so it may be 5 to 6 weeks until I complete the
> task. However, if this is not a problem for you guys, I am more than
> happy to take on the responsibility.
>
> Cheerio,
> B.

Hello Don et al.

Unfortunately, due to the limited amount of resources for open source
related work that we are experiencing and of which we have widely
talked about in the last week or so, I am forced to decline my previous
offer of help with your help (pun intended).

I apologise about this, I always do my best to make good on my offers
and not to let people down, but at the moment I cannot possibly attend
to this task, there are simply not enough hours in the day :-(

I hope this does not upset your plans too drastically and I aplogise
for any inconvenience I may cause.

Kindest regards,
B.
--
                                  Barbara Rosi-Schwartz
                   Etish Limited [http://www.etish.org]
Blog: http://www.brs4etish.blogspot.com
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   ^...^
 /  o,o  \       The proud parents of Useme
 |) ::: (|       The Open Requirements Management Tool
====w=w====      [https://useme.dev.java.net]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Previous Topic:ORMF will not be joining the OSEE project at this time
Next Topic:Ezzat Demnati joins ORMF as a committer
Goto Forum:
  


Current Time: Sat Apr 19 22:01:23 EDT 2014

Powered by FUDForum. Page generated in 0.02595 seconds