Eclipse Community Forums: OSEE » Documentation components

Home » Eclipse Projects » OSEE » Documentation components

Documentation components [message #2097]

Mon, 24 March 2008 15:10

Eclipse User

Hello everyone.

I believe one of the areas on which you OSEE folks were looking for
interested parties to contribute to the environment was "Documentation"
(just from a brief glance at your list of areas post BoF, Don). I would
like to know what exactly you mean by documentation, in order to see if
this is another area in which we (ORMF) might contribute.

If by documentation you mean publication of artifacts, then, as far as
requirements that we handle, we currently provide that.

If you mean user documentation, it is in our long term plans to somehow
generate initial user documentation for those types of requirements
that are amenable to this (for example, use cases).

Or do you mena something completely different?...

TIA and kind regards,
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 #2118 is a reply to message #2097]

Tue, 25 March 2008 23:10

Eclipse User

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.

Re: Documentation components [message #3092 is a reply to message #2118]

Wed, 26 March 2008 11:39

Eclipse User

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 #3182 is a reply to message #3092]

Wed, 26 March 2008 21:19

Eclipse User

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 #3248 is a reply to message #3182]

Thu, 27 March 2008 08:38

Eclipse User

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 #3344 is a reply to message #3248]

Thu, 27 March 2008 13:20

Eclipse User

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 #3675 is a reply to message #3344]

Sat, 29 March 2008 09:43

Eclipse User

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 #3707 is a reply to message #3675]

Sat, 29 March 2008 14:48

Eclipse User

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 #4120 is a reply to message #3707]

Mon, 31 March 2008 13:21

Eclipse User

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 #4261 is a reply to message #4120]

Mon, 31 March 2008 13:29

Eclipse User

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 #4330 is a reply to message #4261]

Tue, 01 April 2008 14:13

Eclipse User

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 #4400 is a reply to message #4330]

Tue, 01 April 2008 14:27

Eclipse User

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 #4470 is a reply to message #4400]

Tue, 01 April 2008 15:25

Eclipse User

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 #4539 is a reply to message #4470]

Wed, 02 April 2008 12:02

Eclipse User

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 #7099 is a reply to message #4400]

Wed, 14 May 2008 08:20

Eclipse User

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 #568332 is a reply to message #2097]

Tue, 25 March 2008 23:10

Eclipse User