EclipseCon Europe 2012

  in a Nutshell

  • A documentation environment
    • synchronized with development artifacts
    • customizable for your development processes
  • Parf of Mylyn docs
  • In incubation phase
  • Parf of Release train since Juno

1. Documentation Sucks

Why does Documentation Suck?

1. Because most of the time it does not exist/contain the infos you need

Why does Documentation Suck?

1. Because most of the time it does not exist/contain the infos you need

Why does nobody write doc?

"Working software over comprehensive documentation"
Agile Manifesto


Don't be short-sighted: Enable your next effort


Why does Documentation Suck?

1. Because most of the time it does not contain what you are looking for.

2. Because most of the time it's outdated -> no one trusts it anymore

Why does Documentation Suck?

1. Because most of the time it does not contain what you are looking for.

2. Because most of the time it's outdated -> no one trusts it anymore

Why is Documentation outdated?

Because keeping your doc synchronized is a burden


That's exactly what Intent is about

2. Synchronize your Doc with Intent

What do we want ?


A mechanism to link documentation parts with technical
artifacts (Java code, models, plug-in dependencies...)

One Intent Document mixing both

Chapter Logical Target Business Architecture {
This chapter aims to describe the system users/actors in scope for
the *Target Architecture*. System actors/users are those users who
*interact with a system*. They can be human or a system/computer.

Section Computer Actors {
One of the most relevant _Computer Actor_ is the *Consistency Checker*.
Whenever changes occur on the Travel Agency database, it verify all consistency constraints defined on the system.
@M
new Actor consistencyCheckerActor {
name = "Consistency Checker";
type = ActorType.Computer;
}
M@
}
[...]

Section Process Steps mapped to Actors {
The *Consistency Checker* Actor participates to the _Consistency Checking_ Process,
which helps achieving the _Manage the data integrity_ Business Objective.
@M
consistencyCheckerActor {
participatesInProcesses += consistencyCheckingProcess;
followObjectives += dataIntegrityObjective;
}
M@
}
}

One Intent Document mixing both

Chapter Logical Target Business Architecture {
This chapter aims to describe the system users/actors in scope for
the *Target Architecture*. System actors/users are those users who
*interact with a system*. They can be human or a system/computer.

Section Computer Actors {
One of the most relevant _Computer Actor_ is the *Consistency Checker*.
Whenever changes occur on the Travel Agency database, it verify all consistency constraints defined on the system.
@M
new Actor consistencyCheckerActor {
name = "Consistency Checker";
type = ActorType.Computer;
}
M@
}
[...]

Section Process Steps mapped to Actors {
The *Consistency Checker* Actor participates to the _Consistency Checking_ Process,
which helps achieving the _Manage the data integrity_ Business Objective.
@M
consistencyCheckerActor {
participatesInProcesses += consistencyCheckingProcess;
followObjectives += dataIntegrityObjective;
}
M@
}
}

One Intent Document mixing both

Chapter Logical Target Business Architecture {
This chapter aims to describe the system users/actors in scope for
the *Target Architecture*. System actors/users are those users who
*interact with a system*. They can be human or a system/computer.

SectionComputer Actors{
One of the most relevant _Computer Actor_ is the *Consistency Checker*.
Whenever changes occur on the Travel Agency database, it verify all consistency constraints defined on the system.
@M
new Actor consistencyCheckerActor {
name = "Consistency Checker";
type = ActorType.Computer;
}
M@
}
[...]

Section Process Steps mapped to Actors {
The *Consistency Checker* Actor participates to the _Consistency Checking_ Process,
which helps achieving the _Manage the data integrity_ Business Objective.
@M
consistencyCheckerActor {
participatesInProcesses += consistencyCheckingProcess;
followObjectives += dataIntegrityObjective;
}
M@
}
}

One Intent Document mixing both

Chapter Logical Target Business Architecture {
This chapter aims to describe the system users/actors in scope for
the *Target Architecture*. System actors/users are those users who
*interact with a system*. They can be human or a system/computer.

SectionComputer Actors{
One of the most relevant _Computer Actor_ is the *Consistency Checker*.
Whenever changes occur on the Travel Agency database, it verify all consistency constraints defined on the system.
@M
new Actor consistencyCheckerActor {
name = "Consistency Checker";
type = ActorType.Computer;
}
M@
}
[...]

Section Process Steps mapped to Actors {
The *Consistency Checker* Actor participates to the _Consistency Checking_ Process,
which helps achieving the _Manage the data integrity_ Business Objective.
@M
consistencyCheckerActor {
participatesInProcesses += consistencyCheckingProcess;
followObjectives += dataIntegrityObjective;
}
M@
}
}

One Intent Document mixing both

Chapter Logical Target Business Architecture {
This chapter aims to describe the system users/actors in scope for
the *Target Architecture*. System actors/users are those users who
*interact with a system*. They can be human or a system/computer.

SectionComputer Actors{
One of the most relevant _Computer Actor_ is the *Consistency Checker*.
Whenever changes occur on the Travel Agency database, it verify all consistency constraints defined on the system.
@M
new Actor consistencyCheckerActor {
name = "Consistency Checker";
type = ActorType.Computer;
}
M@
}
[...]

Section Process Steps mapped to Actors {
The *Consistency Checker* Actor participates to the _Consistency Checking_ Process,
which helps achieving the _Manage the data integrity_ Business Objective.
@M
consistencyCheckerActor {
participatesInProcesses += consistencyCheckingProcess;
followObjectives += dataIntegrityObjective;
}
M@
}
}

3. Intent in Action

Intent applied to Enterprise Architecture

- SmartEA: provides modelers to manage Enterprise Architecture models

- based on the TOGAF methodology






-EA models contain business-critical informations

- Many Documents to store the intents behind EA models

See Demo: how can Intent help documenting EA models

4. Documentation sharing sucks

Intent: behind the Scene

Intent: share your doc in real-time

5. To code synchronization and beyond

Intent Synchronizer


Compares Doc (Model Fragments) with Artifacts (as Models)

Intent Synchronizer


Compares Doc (Model Fragments) with Artifacts (as Models)

Synchronization Bridge


Represent a technical artifact (Java class, plugin.xml...) as a Model

Ariadne: leverage the data of your IDE



- Extracts Technical Artifacts (Java code, GIT commits, bugzilla issues, plugin dependencies...) as Models


- Allows to formalize constraints (automate guidelines checking)

The 3 things to remember about Intent


1. Intent keeps your doc up-to-date with concrete world

2. Intent allows you to check constraints

3. Intent allows real-time collaboration around Doc

Thank You!

Questions asked during the talk

  • Ok, I understood that the Synchronization Bridge mechanism allows to synchronize technical artifacts. What are the current Synchronization Bridges? Can I synchronize Java code?

    > No, not right now. However, we plan to integrate Intent with Ariadne for the Kepler release, and that will allows us to synchronize Java files, Manifests, Mylyn tasks, Git repositories...




  • The Model Fragments syntax of Intent is far too complex for an end-user, could you hide them?

    > Yes, that is one of the things I have in mind. As Intent provides tooling for linking a piece of doc with a technical artifact (Drag'n'Drop) and to fix synchronization issues (quick-fixes), you never have to edit those Model Fragements manually.
    Consequently, we could provide a simplified Intent editor which hides Model Fragments. Then you will just have a pure documentation, that is linked with technical artifacts behind the scene.