Living Documentation

Session Type: 
Standard
Track: 
Eclipse Technology
Experience level: 
Beginner

“Look! It's moving. It's alive. It's alive... it's alive, IT'S ALIVE!”

Documentation and tests are often considered as a write once and never look at again part of most projects, but we believe this isn’t a foregone conclusion. To this end, we’ve developed a new open source tool based on Mylyn Intent to provide a Living Documentation framework.

We need documentation that continues to evolve during the entire product lifetime and provides a single source of truth for our projects. So, we looked for a way to help our team maintaining a shared understanding and guaranteeing a consistent documentation. Even if this type of tool was not part of our usual toolset, we used Eclipse to create a living documentation tool which meets these needs.

After a quick presentation of our sources of inspiration (Acceptance testing, BDD - Behavior Driven Development, executable specification, Cucumber, Jnario...), we will expose the motivation behind the creation of this new tool.

We will show that it not only allows to keep the documentation up-to-date but also to generate the test code structure. Our purpose is to turn computer-focused tests into human-focused documentation. By using a well integrated business-readable syntax (based on Gerkhin) anyone can participate in the creation of specification and automated tests.

We are able to automatically synchronize the documentation with the code and all the existing artifacts of the project (build configuration files, models, source code, test code...).

Finally, a demonstration will show the numerous advantages offered by this approach:

  • Tests that are easier to read and focused on communication
  • Increase capabilities in the area of test automation and reduce duplication in the test code
  • Synchronization and easier navigation through the project artifacts

How are your applications documented? Do you have any documentation at all? If so, is it up-to-date and accurate? Attend this session and come to discuss with us on how to improve tools to document and test software in the 21st century.

Status: 
Accepted
Time slot: 
29 October 16:45 - 17:20
Room: 
Seminarräume 5