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?

Comparable to massive rejection of Unit Testing

"Working software over comprehensive documentation"
Agile Manifesto


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

As a developper, you spend most of your time understanding other people's code.

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

- Pure documentation zones

- Formal links zones

Chapter Significant Scenarios {

This chapter specifies the behavior of the *my.plugin* plugin by listing relevant scenarios.
These scenarios can involve both human actors or computer/system actors, as defined in chapter 1.5.

Section Scenario S-01: get source of a Java method {

*As a* end-user
*Given* a _Java class_ containing a non-abstract method
*Then* when getting the model representation of this Java Class
the source of each method should be the exact source of the java method

@M
@ref "org.eclipse.my.plugin.tests/src/org/eclipse/my/plugin/tests/GetJavaMethodSourceTest.java"
M@
}
}

One Intent Document mixing both

- Pure documentation zones
Explanations in Natural language
Use the Textile syntax

Chapter Significant Scenarios {

This chapter specifies the behavior of the *my.plugin* plugin by listing relevant scenarios.
These scenarios can involve both human actors or computer/system actors, as defined in chapter 1.5.

Section Scenario S-01: get source of a Java method {

*As a* end-user
*Given* a _Java class_ containing a non-abstract method
*Then* when getting the model representation of this Java Class
the source of each method should be the exact source of the java method

@M
@ref "org.eclipse.my.plugin.tests/src/org/eclipse/my/plugin/tests/GetJavaMethodSourceTest.java"
M@
}
}

One Intent Document mixing both

- Formal links zones
Reference to technical artifacts (Java, models, Manifests...)
Extensible behavior (display, hyperlinks, validation...)

Chapter Significant Scenarios {
This chapter specifies the behavior of the *my.plugin* plugin by listing relevant scenarios.
These scenarios can involve both human actors or computer/system actors, as defined in chapter 1.5.

SectionComputer Actors{
*As a* end-user
*Given* a _Java class_ containing a non-abstract method
*Then* when getting the model representation of this Java Class
the source of each method should be the exact source of the java method

@M
@ref "org.eclipse.my.plugin.tests/src/org/eclipse/my/plugin/tests/GetJavaMethodSourceTest.java"
M@
}
}

3. Intent in Action _

To code synchronization and beyond _

Intent Synchronizer


Compares Doc (Formal links) with Artifacts (as Models)

Intent Synchronizer


Compares Doc (Formal links) with Artifacts (as Models)

Synchronization Bridge


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

Intent Synchronizer


Compares Doc (Formal links) with Artifacts (as Models)

Synchronization Bridge


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

4. Checking Constraints Sucks _

Automate high-level constraints checking

You already constraint Development

With informal processes, dev guidelines, good practices...

But high-level constraints are hard to check

Manual reviews: painful, long, error-prone

Automate high-level constraints checking

Plug constraints in Intent

Problem view integration, extensible quick-fixes


5. Documentation sharing sucks _

Intent: behind the Scene

Intent: share your doc in real-time

Intent: there's more


- HTML Bootstrap export (focused on navigation)

- Xtext integration, new bridges...

- Performances & Stability

Last minute slide



Mylyn 4.0 will store tasks, bugzillas, git repos... as models


Imagine what Intent could do!


- Alice is writing a contribution guide showing the git repo URL
-> And if URL changes, sync. issues will be raised


- John is closing a bugzilla issue without writing Junit test
-> Intent will raise a validation issue as team defined custom rule

The 3 things to remember about Intent


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


2. Intent allows you formalize your dev constraints


3. Intent allows real-time collaboration around Doc

Intent Needs You

Give us feedback

We do take community feedbacks in account
You're driving this ship!
- Syntax simplification
- Java bridge...



Technical contributions

- Sync. bridges, validation rules, new repository back-ends...
- Become an Intent committer!










Thank You!