In case you’re not aware (yet ;) ) the Mylyn Intent proposal is going forward — if everything goes well we’ll be able to get a shiny git repository on Eclipse.org in the incoming weeks.
Mylyn Intent is going to help you co-document and design things. As we consider that code activity is part of the design itself, the tool analyzes your source code and projects to assist documenting it.
What does “assist” mean in this context?
At any time, you can synchronize your documentation artifacts regarding the corresponding models and source code. The really interesting things happen when it is not synchronized: you’ll then be able to compare the expected design versus the actual one and, either update the doc, or update the code depending on what makes sense.
The “design” word has a broad meaning, and indeed under this term we place anything that we formalize through an Ecore model.
It really is up to your team and development process. Here is an example of what you could want to capture if you develop Eclipse plugins:
This one is pretty flexible and straightforward; you could come up with a slightly more complex model taking in account the versioning and change management aspects.
Basically this model captures every feature targeting either the end users or the developers. For a developer feature, one has to associate at least one corresponding API exported by a bundle; for each API, one has to associate the corresponding unit tests. For an end user feature, an acceptance test is required and it should be associated to an interaction (this part is left as an exercise to the reader ;)).
I already hear you screaming: but you said it would be fun to document!? I’ll have to fill all that information?
Don’t panic.
With a blue highlight now: the things which are going to be synchronized with your development environment. What does that mean? It means you won’t have to dig yourself through the code finding unit tests, filling the bundle and exported packages — Intent will do this for you and will be able to quickly update your documentation. Furthermore, once you’re back on coding, Intent will still work and check that your changes are in sync with the doc, telling you when it’s not.
The non-blue things — you’ll have to describe those in your document; Intent really can’t figure it out for you.
Please note that this is an example of what can be achieved plugging a specific model and the corresponding synchronization code in Intent; you’ll be able to plug-in your own very soon.
Let’s go back to the point: what does Intent offer then as a platform? What does Alice have to do with this? How does she look like?
You’ll figure it out at EclipseCon on Tuesday 22th, in Steven Creek at 11:10. Don’t miss it.