Can you make design documentation fun?

The Atlas Copco Industrial Techniques business area offers the most extensive range of industrial power tools and assembly systems on the market. As part of Atlas Copco Industrial Technique’s Automotive Spice (ASPICE) improvement program Addalot and Atlas Copco have worked with the improvement of the system design documentation and requirements traceability. This experience was presented at the 3^rd Scandinavian Conference on System and Software Safety in Stockholm in March.

ASPICE puts concrete requirements on the system design documents and requirements traceability. The initial assessments showed that Atlas Copco did not fulfill these requirements, and we needed to establish this documentation and traceability. The system in question had been developed over several years in Rhapsody, but the overall system documentation that was originally written was neither complete nor up to date even if some documentation existed in various forms. So we needed to create something more or less from scratch,

This was done in the following three activities:

An outline for the architecture description was established based on discussion with the architect and the ASPICE requirements. Addalot collected existing material and put that into the draft document. Then specialists for the different areas were assigned and  Addalot  interviewed the experts, and documented the different parts of the architecture with constant review and feedback form the architect. This resulted in a 70 page document. To establish a traceability to the detailed design we made an index at the end of the document where the different components were described, and ensured that all SW components were put into context in the architecture document.

The detailed design documents were made by selecting one component as a pilot, and making documentation of that. This was reviewed by a group of experts so that we had a good example. The components were distributed among the software developers to be documented. Addalot reviewed all the design descriptions to ensure that they had the right level of information, and also that there was a natural connection between the architecture description as well as the Rhapsody model/code. The technical content of the detailed design documents were reviewed by peer developers. The system consists of about 60-70 components, most containing 5-10 classes and having a main façade class that handles the interface.

The requirements to the system were kept in the Caliber RM tool. During the course of this project Atlas Copco hired a requirements coordinator who started to clean up and improve the requirements. The traceability is established by linking each requirement to one SW component, i.e. the component that has the major responsibility for implementing this requirement. Each “section” in Caliber is allocated to a SW developer who is responsible for establishing the traceability. Traceability to test was already established as each test case was linked to a requirement.

Experiences

• Atlas Copco was quite skeptical in the beginning
  • Documentation is heavy and no one has the extra time to write
  • Can this be done by someone from the outside? The system is too complex!
• Atlas Copco had a strong need for better documentation, i.e
  • Many new employees
  • It was hard to get an overview of the system
  • Experts were consulted all the time
  • Quality problems
• Atlas Copco’s initial experience
  • It was simpler than Atlas Copco thought - it was valuable to get it documented
  • The use of Addalot helped focusing and driving the work
  • Several areas needing improvements have been revealed and agreed upon
  • Easier to do impact analysis
  • Increased competence within organization
  • Easier for new employees to understand the system
  • The work has been well received by the customer requiring the ASPICE compliance
• Atlas Copco’s experience after some months (Added after the conference presentation)
  • Less friction within / between the teams since it is clearer what should be done and that there is information to read about what the other teams are doing
  • Clearer boundaries for what should be implemented
  • Better time estimation 
  • What are implemented will also be documented
  • The overall ASPICE improvement work has led to more structured and efficient work

Atlas Copco is an industrial group with world-leading positions in compressors, expanders and air treatment systems, construction and mining equipment, power tools and assembly systems. With innovative products and services, Atlas Copco delivers solutions for sustainable productivity. The company was founded in 1873, is based in Stockholm, Sweden, and has a global reach spanning about 180 countries. In 2013, Atlas Copco had 40 200 employees and revenues of BSEK 84 (BEUR 9.7).
Learn more at www.atlascopco.com.

Atlas Copco’s Industrial Technique business area provides industrial power tools, assembly systems, quality assurance products, software and services through a global network. It innovates for sustainable productivity for customers in the automotive and aerospace industries, industrial manufacturing and maintenance, and in vehicle service. Principal product development and manufacturing units are located in Sweden, France and Japan. 



Atlas Copco’s Industrial Technique recruits talented software engineers who will contribute in the development of their products in an expanding market.