Skip to main content
Jump to: navigation, search

Difference between revisions of "Intent/Use Cases"

 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Intent can be used in a lot of use cases, from Literate Modeling to ALM, from Doc Driven Development to software migration. We will try here to present typical use cases of Intent.
+
<br>
  
= Use Case 1 : Doc Driven Development =
+
''THIS PAGE IS A WORK IN PROGRESS''
  
Alice works in a ten people team in charge...
+
This section is focused on describing Intent's main use cases, some features to support these use case might not be completely implemented yet but are at the top of the priority list.
One of their customers wants a new feature (mostly IHM) : a ''customer page'' allowing to search through all customers with several parameters and filters.
+
  
Of course, Alice could directly modify the code, and Intent will then detect synchronization issues and propose quick-fixes for synchronizing code doc with code, but as we will see Doc Driven Development presents some major advantages.
+
== Retro-documentation of Existing Code  ==
  
== Documentation & metamodels ==
+
The Intent project considers that code and documentation have the same value, and that no one should necessarily be the first on the other. Its focus is on making sure these are synchronized and helping the developper to keep them synchronized. One of the consequences of this statement is that it's a perfect tool to get started in documenting legacy code.
  
Presentation of the Intent document (meta-model, structure) used by the team to capture design choices.
+
{{Intent-Header{{{watch|}}} | title=
 +
|editpage=Intent
 +
|border= #C3C3E5          <!-- H120 S15 V75 the color of the borders around Box Sections -->
 +
|titleforeground=#443266  <!-- This is the color of the Box Section Title Bar text -->
 +
|titlebackground=#C3C3E5  <!-- H120 S40 V85 the color of the Box Section Title Bar -->
 +
|background=#f0edf8      <!-- H120 S4 V100 the color of the Box Section background -->
 +
|foreground=black}}      <!-- This is the color of the Box Section text -->
 +
Let's take an sample scenario for this usage :
  
== Step 1 : Getting the parts to update ==
+
Alice want to document its existing Eclipse project, she starts a new empty documentation project.
 +
 
 +
Alice starts to organize the documentation through sections an ''introduction'', a ''general design'' chapter and another ''dedicated to testing''...
 +
 
 +
Alice has the ability '''in the documentation ''' to declare model fragments describing her application :
 +
 
 +
<pre>@M
 +
  new PluginProject coreplugin {
 +
    id = "com.alicecompany.greatapp.core"
 +
  }
 +
@M
 +
 
 +
This @plugin@ contains all the core services of *greatapp* [..] .
 +
 
 +
</pre>
 +
 
 +
 
 +
Alice describes, in a documentation section dedicated to the general architecture of her great app, &nbsp;the list of every PluginProject described using natural langage.
 +
 
 +
In another chapter dedicated to the technical architecture, she uses the ability to complement her definition of the plugins and describes the Java execution environment:
 +
 
 +
<pre>@M
 +
coreplugin {
 +
  executionEnvironement = "J2SE-1.5"
 +
}
 +
M@</pre>
 +
 
 +
When Alice hits the save button, her document is being compared with her workspace content; if any de-synchronization is detected, markers are added at the corresponding position in the document.
 +
 
 +
The PluginProject model definition enforces the fact that every PluginProject has to describe its API (exported packages and extension points) in the documentation.&nbsp;During the synchronization, an error will be added on every PluginProject which is - in the workspace - providing an API which is not referenced in the documentation.
 +
 
 +
 
 +
Alice might either fix those errors manually, adding the corresponding model fragments, or hit the quickfix intializing those:
 +
<pre>@M
 +
corePlugin {
 +
  extension-points += new ExtensionPoint {
 +
        id="thing-provider"
 +
  }
 +
}
 +
M@
 +
 
 +
bq. TODO ALICE : describe the extension point
 +
 
 +
@M
 +
corePlugin {
 +
  extension-points += new ExtensionPoint {
 +
        id="compilation-participant"
 +
  }
 +
@M
 +
 
 +
bq. TODO ALICE : describe the extension point
 +
 
 +
</pre>
 +
 
 +
In a nutshell, using the validation errors and quickfixes Alice is going to retro-document the whole project. Furthermore, once this is done, any rebuild of the documentation will check the development artifacts (Manifest.MF, plugin.xml and others) and will report inconsistencies.
 +
 
 +
This example is using EclipsePlugin as - in fact - an example, the ability to synchronize model fragments to "'''real world artifacts'''" &nbsp;is a completely extensible part of Intent powered by EMF models.
 +
{{Intent-footer}}
 +
 
 +
 
 +
== Document-Driven Design  ==
 +
 
 +
Now that Alice has documented her plugins, she can develop new features through documentation. Of course, she still can develop the new feature and retro-document it (see previous use case).
 +
 
 +
=== Step 1 : Getting the parts to update ===
  
 
In a regular development process, Alice would have had to determine the components to update, without many help. How many of you have used the Eclipse's ''Open Type'' wizard and search for Java Classes with a name that may indicate that it is doing what you are searching for ?
 
In a regular development process, Alice would have had to determine the components to update, without many help. How many of you have used the Eclipse's ''Open Type'' wizard and search for Java Classes with a name that may indicate that it is doing what you are searching for ?
With Doc Driven Development, you first have to determine what parts of the documentation have to be changed/deleted/created.
+
 
 +
With Doc Driven Design, you first have to determine what parts of the documentation have to be changed/deleted/created.
  
 
To do so, Intent provides tools to enhance searches. Alice has two solutions :  
 
To do so, Intent provides tools to enhance searches. Alice has two solutions :  
Line 21: Line 92:
 
from the table of contents, she identifies the chapters/sections related to UI features. In some cases, it can be really quick, especially if the documentation has been well-structured.
 
from the table of contents, she identifies the chapters/sections related to UI features. In some cases, it can be really quick, especially if the documentation has been well-structured.
 
* searching for all document parts related to a model element :
 
* searching for all document parts related to a model element :
if Alice has some basicall knowledge of the meta-model, she should know that the UI feature should be added .... If she has not, she will have to quickly read the ''meta-model overview'' section.
+
if Alice has some basicall knowledge of the meta-model, she should know what model elements are related to the feature she wants to develop. If she has not, she will have to quickly read the ''meta-model overview'' section.
 +
 
 +
=== Step 2 : updating doc ===
 +
 
 +
TBD
 +
 
 +
<!--
 +
Adding feature, justify and explain intents
 +
 
 +
what she had in mind before reading the doc was incorrect, she
 +
-->
 +
 
 +
=== Step 3 : validation of the new feature ===
 +
 
 +
TBD
 +
 
 +
<!--
 +
Automatic and useful : Alice made an design error that would have cost her a lot if she was directly modifying code. Quick-fixes
 +
 
 +
-->
 +
=== Step 4 : synchronization ===
  
== Step 2 : updating doc ==
+
TBD
  
Adding feature + justify and explain intents
+
<!--
what she had in mind before reading the doc was incorrect
+
Quick-fixes and there it is
 +
-->
  
== Step 3 : validation of the new feature ==
+
=== Conclusion ===
  
Automatic and useful : Alice made an design error that would have cost her a lot if she was directly modifying code. Quick-fix
+
By adding a few lines in the ''Document'', and '''justifying''' her design choices, Alice has quickly obtained a skeleton of the code, and is sure that her feature is valid, properly documented and can be understood by future readers who will have to maintain this feature.
  
== Step 4 : synchronization ==
+
== Screenshots  ==
Quick-fix and there it is
+
  
== Conclusion ==
+
Searching through documentation using outline&nbsp;:
By adding a few lines in the ''Document'', and '''justifying''' her design choices, Alice has quickly obtained a skeleton of the code, and is sure that her feature is valid, properly documented and can be understood by future readers who will have to maintain this feature. A lot quicker than ...
+
  
= Intent as a environment synchronizer ==
+
[[Image:Intent outline search.png|450x221px|450x221px[450x221]]
  
Sharing TP
+
Getting synchronization issues between documentation and models concretely used by developers&nbsp;&nbsp;:
  
= Intent & ALM =
+
[[Image:Intent synchronizer example.png|400x201px|400x203px[400x203]]

Latest revision as of 05:10, 18 March 2011


THIS PAGE IS A WORK IN PROGRESS

This section is focused on describing Intent's main use cases, some features to support these use case might not be completely implemented yet but are at the top of the priority list.

Retro-documentation of Existing Code

The Intent project considers that code and documentation have the same value, and that no one should necessarily be the first on the other. Its focus is on making sure these are synchronized and helping the developper to keep them synchronized. One of the consequences of this statement is that it's a perfect tool to get started in documenting legacy code.

Let's take an sample scenario for this usage :

Alice want to document its existing Eclipse project, she starts a new empty documentation project.

Alice starts to organize the documentation through sections an introduction, a general design chapter and another dedicated to testing...

Alice has the ability in the documentation to declare model fragments describing her application :

@M
   new PluginProject coreplugin {
     id = "com.alicecompany.greatapp.core"
  }
@M

This @plugin@ contains all the core services of *greatapp* [..] .


Alice describes, in a documentation section dedicated to the general architecture of her great app,  the list of every PluginProject described using natural langage.

In another chapter dedicated to the technical architecture, she uses the ability to complement her definition of the plugins and describes the Java execution environment:

@M
coreplugin {
  executionEnvironement = "J2SE-1.5"
}
M@

When Alice hits the save button, her document is being compared with her workspace content; if any de-synchronization is detected, markers are added at the corresponding position in the document.

The PluginProject model definition enforces the fact that every PluginProject has to describe its API (exported packages and extension points) in the documentation. During the synchronization, an error will be added on every PluginProject which is - in the workspace - providing an API which is not referenced in the documentation.


Alice might either fix those errors manually, adding the corresponding model fragments, or hit the quickfix intializing those:

@M
corePlugin {
   extension-points += new ExtensionPoint { 
         id="thing-provider"
   }
}
M@

bq. TODO ALICE : describe the extension point

@M
corePlugin {
   extension-points += new ExtensionPoint {
         id="compilation-participant"
   }
@M

bq. TODO ALICE : describe the extension point

In a nutshell, using the validation errors and quickfixes Alice is going to retro-document the whole project. Furthermore, once this is done, any rebuild of the documentation will check the development artifacts (Manifest.MF, plugin.xml and others) and will report inconsistencies.

This example is using EclipsePlugin as - in fact - an example, the ability to synchronize model fragments to "real world artifacts"  is a completely extensible part of Intent powered by EMF models.


Document-Driven Design

Now that Alice has documented her plugins, she can develop new features through documentation. Of course, she still can develop the new feature and retro-document it (see previous use case).

Step 1 : Getting the parts to update

In a regular development process, Alice would have had to determine the components to update, without many help. How many of you have used the Eclipse's Open Type wizard and search for Java Classes with a name that may indicate that it is doing what you are searching for ?

With Doc Driven Design, you first have to determine what parts of the documentation have to be changed/deleted/created.

To do so, Intent provides tools to enhance searches. Alice has two solutions :

  • searching through the documentation as if it was a paper doc :

from the table of contents, she identifies the chapters/sections related to UI features. In some cases, it can be really quick, especially if the documentation has been well-structured.

  • searching for all document parts related to a model element :

if Alice has some basicall knowledge of the meta-model, she should know what model elements are related to the feature she wants to develop. If she has not, she will have to quickly read the meta-model overview section.

Step 2 : updating doc

TBD


Step 3 : validation of the new feature

TBD

Step 4 : synchronization

TBD


Conclusion

By adding a few lines in the Document, and justifying her design choices, Alice has quickly obtained a skeleton of the code, and is sure that her feature is valid, properly documented and can be understood by future readers who will have to maintain this feature.

Screenshots

Searching through documentation using outline :

450x221px[450x221

Getting synchronization issues between documentation and models concretely used by developers  :

400x203px[400x203

Back to the top