Intent Discovery - Part 1 : the intents behind softwares

Alice looking at some code: «Hey, why is this thing designed this way ? It looks way more twisted than necessary» Bob : “Just check the design documents.”laughs

Nowadays, you can find tools for basically any Developer or Architect task, no matter how complex. How come, then, any developer will tell you how hard it is to achieve a task as simple as updating a doc ?

When it is a 500 pages bloc and the feature you developed should be mentioned in 15 different chapters, you may even spend more time updating doc that you have spent developing and testing the feature itself… Any big software released at least 2 years ago contains errors in its documentation, as no one has time for reading the 500 pages and check the doc consistency.

This post is tempting to explain :

Why the knowledge behind softwares cannot be properly captured without Documentation Why Documentation update is a nightmare How Intent, by representing Documentation,  Models and development artifacts as a whole, and providing tooling for writing useful doc, will try to reconcile developers with documentation writing.

The intents behind softwares

Intent claims itself to be a tool helping developers to write doc. But what is doc exactly ? Too many times, I hear developers saying things like “just read the doc”, when actually they are talking about javadoc. Don’t misunderstand me, javadoc is great, and I use it all the time and rigorously. But such a doc is so tight with code structure that it is not appropriate to show the intents behind a software : how would I explain the design choices I made when focusing on a Java Class ?

I should not have to stress out how important are concerns and design choices understanding : first of all, when your team grows up, newcomers should quickly and fully understand the spirit of your software architecture, to be able to maintain and to improve your software (which is basically what they are paid for). What is more, I challenge you to explain clearly the design choices you made on a project six months ago ; I am sure that you will forget an important concern.

To present the intents behind softwares, developers do write doc, although they are often doing it because of their project manager pressure. Such “paper doc”  is written with pure documentation languages (like Textile, MediaWiki, Latex, HTML, open office…). I think any developer who had to maintain this kind of doc up-to-date with the changes made on their software will agree : paper doc synchronization is quite a burden. How come achieving such a common task should be so difficult, comparing to all the complex tasks we handle everyday thanks to the appropriate tooling ?

Code, Models and Documentation desynchronization

Let us consider the different ways that can be used to represent the knowledge behind a software. We identify three different spaces, each space bringing a different kind of knowledge to the software.

The Technical Space contains you source code and all your configuration files. It brings a concrete knowledge of the software, describing exactly its properties and what it is going to do. It is hard to capture the intents behind the software from this viewpoint : for example, it is nearly impossible to determine what part of the code allows to fulfill a given requirement. Again, javadoc’s scope is too reduced to allow high-level knowledge sharing (“I see the trees, but where is the Forest ?”).

The Model Space brings a more formal knowledge of your software : it allows to formalize requirements and to specify your software’s main entities and architecture. However, it is still very hard to determine, by studying models, the design choices that have been made by the Architect, and the underlying concerns and requirements from which they have been decided.

The Document Space provides a global knowledge of your software. Using natural language, it is way easier to explain the intents behind the models and code. Moreover, it is structured following a stream of consciousness order : one can structure a document by concerns (one part for all the code and models that ensure persistency of datas, one part dealing with security issues…), another would prefer to structure it following each requirements… In result, a reader will be able to discover the software step by step, with an high-level view of each main requirements and design decision.

These 3 spaces all provide useful informations about your software. However, if synchronization between Models and Code has been improved during the last few years (with code generation tools like Acceleo, Traceability tools, and reverse engineering tools), there is clearly a lack of automatic processes to keep documentation up-to-date with the Model and Technical spaces.  

Intent provides tooling for keeping the documentation up-to-date with any Model, as it will be detailed in next posts. As any development artifact (whether it is a Java class, a plugin dependency, an Acceleo script, a Mylyn task…) can be represented as a model, Intent will allow to synchronize the documentation with any “concrete” information.

Intent’s purpose : reconcile developers with documentation

Intent provides tooling for : 

creating a complete documentation. As each developer has its favorite paper doc language, the concrete syntax for the documentation will be opened (one can choose Textile, another one HTML or Latex). defining model fragments with a textual syntax. As it has been shown by all the M.D.E. users, DSLs are a good way to simplify design. That is why Intent will provide extension points to allow users to use the correct textual DSL according to what they want to describe (for example, one DSL for describing your plugin dependencies, and an other for describing Ecore models). Such DSLs may be created from scratch or through the use of Language Development Frameworks like Xtext. an authoring tool with appropriate tooling, allowing users to search for all documentation parts related to a concern or a model element, to compile and validate the described models, providing code completion and quick-fixes… synchronizing the described model fragments with the concrete world referencing precisely development artifacts directly inside the documentation (for example : “the development of this feature has been divided in 3 tasks : <reference to the corresponding mylyn tasks>”).

Writing doc becomes as fun and useful as writing doc !

An important point to notice is that Intent allows developers to start writing code and synchronize it with their doc or writing doc and synchronize it with their development artifacts ; just use the right tool for the task.

Benefits of writing documentation with Intent

I am aware that I have not presented enough features of Intent to convince you of all the benefits it brings. Let me leave you with some benefits based on common sense. 

First of all, as Intent is fully integrated to the Eclipse IDE, you will not have to toggle from your IDE to Open Office any more. As it is compliant with all design tools (graphical modelers for example) and all the Eclipse projects for which bridges will be developed, writing doc is no longer a burden.

As updating documentation becomes straightforward, doc is now really useful : it finally describes your software, and not what your software used to look like 2 years ago. As the documentation related to a part of code or model is kept around its definition, it is very easy to search through the documentation and find all code related to one concern, or all concerns related to a Class. Of course, a doc up-to-date improves the maintainability of your software, and will help to avoid misunderstanding issues. Such a doc also provides a high-level knowledge of your software. Donald Knuth speaks about Bird’s Eye View.

Actually, your doc becomes more than a doc : you can use it for synchronizing all your development artifacts, from requirements coverage to development environment.

Many other benefits related to collaborative design, developers daily work and Application Lifecycle Management will be presented later.

Next post : How does the Intent syntax allow to split design across concerns

If you liked this post, you can read the Eclipse proposal of the Intent project and provide us feedback here. If you want to follow the Intent project, go check our Twitter account.