Something is Rotten in the State of Documenting Simulink Models

Vera Pantelic, Alexander Schaap, Alan Wassyng, Victor Bandur and Mark Lawford

McMaster Centre for Software Certiﬁcation, McMaster University,

Keywords:

Model-Based Development, Simulink, Software Documentation, Embedded Software, Software Require-

ments Speciﬁcation, Software Design Description.

Abstract:

In this paper we draw on our experience in the automotive industry to portray the clear need for proper docu-

mentation of Simulink models when they describe the implementations of embedded systems. We effectively

discredit the “model is documentation” motto that has been hounding the model-based paradigm of soft-

ware development. The state of the art of documentation of Simulink designs of embedded systems, both

in academia and industrial practice, is reviewed. We posit that lack of proper documentation is costing in-

dustry dearly, and propose that a signiﬁcant change in development culture is needed to properly position

documentation within the software development process. Further, we discuss what is required to foster such a

culture.

1 INTRODUCTION

We have witnessed ﬁrst-hand, in industry, and es-

pecially while working with large automotive orig-

inal equipment manufacturers (OEMs) and automo-

tive suppliers, the detrimental effect of non-existent

or poor software documentation. Other researchers

also have traced the poor quality of software engi-

neering practices in industry to the lack of appro-

priate software documentation (Sousa and Moreira,

1998). Some, most notably David Parnas, have iden-

tiﬁed improper software documentation as the prime

cause of industry’s erratic record regarding software

quality (Parnas, 2011). While the cost of lack of

proper documentation is hard to measure, we provide

anecdotal evidence that illustrates its effects in devel-

opment and maintenance of production-scale embed-

ded systems in Simulink/Stateﬂow. We believe that

these effects often translate to large ﬁnancial losses

for companies.

“Models are documentation” has followed model-

based design (MBD) since its early phases, primarily

promoted by tool vendors (e.g. (Barnard, 2005; Br

uck

et al., 2002)). However, our experience clearly indi-

cates that any developer that has ever been tasked with

reverse-engineering a large industrial-scale Simulink

model understands all too well that a Simulink model

is not complete enough documentation. A Simulink

model is only one view of the system being imple-

mented – albeit an executable one. However, differ-

ent stakeholders need different views: the developer

of model A needs to understand the model’s inner-

working, while the developer of model B, which in-

terfaces with A, needs to know only the interface of

A. It is important to note here that we mean both the

syntax and semantics of the interface. Simulink pro-

vides the syntax of the interface of A. Additional doc-

umentation is necessary to provide the semantics. In

addition, the developer of A needs to document ratio-

nale of design decisions made in the implementation

of A. The crucial problem is that this additional in-

formation is rarely documented, even though history

teaches us how important it is (Sagoo et al., 2014).

From our experience, many developers appreciate

the beneﬁts of good software documentation. Refac-

toring large industrial-scale Simulink models is prac-

tically impossible without good documentation. In

fact, developers have asked us on different occasions

to help them document Simulink models as – or,

rather, because – they were going through a gruelling

process of refactoring another engineer’s model. Fur-

ther, the same developers cited “lack of documenta-

tion culture” as the main cause for not creating and/or

properly maintaining software documentation – pro-

duction and proper maintenance of documentation is

not part of the companies’ values and expected be-

haviour of their developers. Documentation efforts

are not appreciated, and thus seldom rewarded, even

during (intense) reverse-engineering activities when

their beneﬁts become painfully obvious.

Pantelic, V., Schaap, A., Wassyng, A., Bandur, V. and Lawford, M.

Something is Rotten in the State of Documenting Simulink Models.

DOI: 10.5220/0007586005030510

In Proceedings of the 7th International Conference on Model-Driven Engineering and Software Development (MODELSWARD 2019), pages 503-510

ISBN: 978-989-758-358-2

503

This paper surveys the state of the art in the docu-

mentation of Simulink implementations of embedded

systems, in both academia and industry. In particu-

lar, we present our experience distilled from collab-

orations with multiple automotive OEMs and suppli-

ers to illustrate the industrial need for good documen-

tation of Simulink models of embedded controllers.

Also, we address existing work and existing tool sup-

port, and discuss their possible extensions that could

provide proper support for the documentation pro-

cess. Therefore, our position is that proper Simulink

model documentation would be a cost-effective so-

lution for proper maintenance of production-scale

Simulink models. However, this would require a large

cultural change in how the industry perceives docu-

mentation. This change would require investment in

providing technical support for efﬁcient creation and

maintenance of documentation, including proper tool-

ing to support these activities.

The rest of this paper is structured as follows:

Section 2 describes what documents would be useful

companions to Simulink models and why. Section 3

presents some of our relevant experience with indus-

trial Simulink models and explains why these docu-

ments are crucially important for large modeling ef-

forts. Section 4 reviews currently available support

for documenting Simulink models and Section 5 de-

scribes our position on the need for cultural change

regarding software documentation. We conclude in

Section 6.

2 DOCUMENTING SIMULINK

MODELS: WHAT AND WHY?

The application layer of embedded automotive soft-

ware is often designed in Simulink/Stateﬂow. For

large controllers, the design consists of dozens of

large Simulink/Stateﬂow models, where the largest

models contain hundreds of thousands of blocks and a

few tens of thousands of subsystems. Each Simulink

model is typically assigned to one developer. There-

fore, a Simulink model corresponds to a software

module, in the spirit of the module’s deﬁnition as a

responsibility assignment (Parnas, 1972).

In this context there are many reasons why soft-

ware documentation is essential, and they all revolve

around communication. Every document communi-

cates a different aspect of the software, offering a

useful abstraction to its users. These aspects need to

be communicated between domain experts, software

developers, managers/supervisors, reviewers, testers,

maintainers, certiﬁcation authorities, and users. Doc-

umentation is critical not only for communication

in the forward development process but also during

maintenance. In particular, traceability is now rec-

ognized to be essential in achieving and maintain-

ing safety, security and dependability (Mader et al.,

2013). Traceability includes bi-directional links be-

tween system development artifacts, as well as be-

tween entities in development and veriﬁcation, and

between system development documents and assur-

ance cases. Without adequate traceability, change im-

pact analysis becomes fragile, and incremental de-

velopment a nightmare. Thus, our documentation

must include the capability to record links between

all these entities – far beyond what is achievable in

Simulink alone. In regulated industries, documenta-

tion is needed for compliance with relevant standards.

In particular, in the automotive industry proper soft-

ware documentation is required by ISO 26262 (ISO,

2011). However, the standard imposes almost no re-

quirements on the content and format of the docu-

ments. This is not surprising – software standards

typically fail to do so.

Just as in traditional software development, when

developing software in Simulink/Stateﬂow, two doc-

uments are crucial (Bialy et al., 2017; Schaap et al.,

2018). The ﬁrst is the model’s Software Requirements

Speciﬁcation (SRS), specifying the model’s black-box

behaviour. The document acts as a contract between

the model’s developer and the developers of other

models that interact with it. It is a document that

dictates what the model should implement. Also, the

SRS is a reference document for veriﬁcation activi-

ties, where it can be used as a testing oracle. Most

importantly, the SRS describes what the software

must do at a higher abstraction level than would ever

be possible when describing exactly how the soft-

ware will achieve the required behaviour – as is the

case in Simulink. As further motivation for SRSs

in the automotive domain, ISO 26262 strongly rec-

ommends requirements-based testing for electronic-

software components, no matter what Automotive

Safety Integrity Level (ASIL) they are assigned.

The second document is the Software Design De-

scription, describing a model’s internal design that

satisﬁes its requirements. It captures design deci-

sions and anticipated changes, and is written and used

by the model’s developers in both development and

maintenance. The document structure should reﬂect

the model’s subsystem

hierarchy, documenting the

interface and internal design for each important sub-

system (Schaap et al., 2018). As described earlier in

Section 1, Simulink provides a syntactic deﬁnition of

interfaces, but it is important that we also provide a

Simulink uses a notion of subsystem to organize large

models hierarchically.

MODELSWARD 2019 - 7th International Conference on Model-Driven Engineering and Software Development

504

semantic deﬁnition of the interfaces. The semantic

deﬁnition has to be added to Simulink, either locally

within the model, or in external documentation. The

semantic deﬁnition often needs to be supported by ra-

tionale, trace-links to requirements, etc. This kind of

information is extremely difﬁcult or even impossible

to reconstruct years after the initial development of

the model. This document is therefore crucially im-

portant, as the maintainers are typically not the orig-

inal developers. Regarding the syntactic deﬁnition

of the interface of a Simulink subsystem, although

contained within the subsystem, this deﬁnition does

not currently have an explicit representation within

Simulink. This is due to the fact that, besides the

explicit data ﬂow from and into a subsystem repre-

sented using input and output ports, Simulink subsys-

tems can communicate via implicit data ﬂow mech-

anisms – data stores (analogous to variables in tra-

ditional programming languages) and Goto/Froms. A

proposal has been made on how to explicitly docu-

ment the syntactic deﬁnition of a model’s complete

interface (Bender et al., 2015).

3 CURRENT PRACTICE IS NOT

GOOD ENOUGH

In general, software documentation is often outdated,

non-existent, poorly written and generally untrust-

worthy (Parnas, 2011; Lethbridge et al., 2003). The

same is true speciﬁcally of documentation in MBD

with Simulink (Rau, 2002; Ackermann et al., 2010;

Bialy et al., 2017; Schaap et al., 2018). Our experi-

ence in the automotive industry corroborates this per-

ception. There is a fundamental difference between

software engineering and traditional engineering dis-

ciplines in that, in software development, there is no

immediate material cost associated with producing

some prototype of the ﬁnal product. In traditional en-

gineering, there is a tangible cost above time and ef-

fort in building a prototype. Thus, even before a pro-

totype is attempted, initial analyses and preliminary

requirements are documented. Since we want to reap

as many beneﬁts as possible from the cost of the pro-

totype(s), lessons learned in terms of rationale, design

choices etc., are recorded for later use during the con-

struction of the prototype. However, with software

there is the perception that it costs nothing to quickly

and sloppily “hammer out” code to see if we can make

it work as intended. In software, this initial artifact is

the ﬁrst nail in the cofﬁn of proper documentation.

To make matters worse, industrial culture regards this

initial quick and dirty prototype as initiative on the

developers’ part and as a meaningful ﬁrst step toward

a solution. Under this type of work culture, effective

documentation is promptly and effectively short-cut,

with all subsequent effort invested in evolving this ini-

tial artifact.

3.1 Stories

To illustrate the impact of lack of (proper) documen-

tation of Simulink/Stateﬂow models in industry, we

summarize some of our experience gained through

interactions with automotive industrial partners. The

following stories highlight the large development and

maintenance costs attributable to a lack of appropriate

documentation.

Anecdote 1. A module of an automotive controller

implemented a complicated optimization algorithm in

Simulink. During the maintenance phase of the soft-

ware development life cycle, the module was identi-

ﬁed as an efﬁciency bottleneck, and a domain expert

was tasked with refactoring it. However, the model it-

self was sparsely documented, and additionally, used

another algorithm that itself was sparsely documented

in the literature. Furthermore, it was not clear why

some corner cases were implemented in a particular

way: the rationale was lost as the original develop-

ers of the model were no longer available. Another

complication was that the rationale for the design de-

cisions for using certain Simulink blocks over others

was also lost. In the reverse-engineering process, the

domain expert had to repeatedly consult an engineer

who was the only one in the company with a deep

understanding of the model. This is a quite common

scenario that we experienced on many occasions: the

maintenance efforts typically involve consulting dif-

ferent experts in an attempt to understand the model,

resulting in a large waste of valuable resources. In this

particular case, the domain expert had spent several

months reverse-engineering the module and ended up

consulting us for help in documenting the algorithm

of interest. To the best of our knowledge, the perfor-

mance bottleneck was never addressed.

Anecdote 2. A collaboration with an industrial

partner included development of the plan for the mi-

gration of the existing software to AUTOSAR, the

open automotive software architecture (AUTOSAR,

2018). In particular, the network interfaces, including

CAN (Controller Area Network), SPI (Serial Periph-

eral Interface) and LIN (Local Interconnect Network),

as well as diagnostics, were non-compliant with AU-

TOSAR, thus requiring an overhaul of the exist-

ing solution, including a new, AUTOSAR-compliant

mechanism for communication at the application

layer, where Simulink models were used. How-

ever, the existing communication/diagnostics mech-

Something is Rotten in the State of Documenting Simulink Models

505

anisms/blocks at the Simulink level were poorly doc-

umented. The lack of proper documentation rep-

resented a notable hurdle in the development of

the migration plan that instigated numerous inter-

actions with both engineers at the application level

(Simulink) and the base software level.

Both stories above clearly depict the costs associ-

ated with inadequate documentation. During the soft-

ware maintenance phase, trying to understand under-

documented models leads to waste of valuable re-

sources. Reverse-engineering is notoriously difﬁcult,

even for domain experts: a great amount of time and

effort in addition to domain-speciﬁc knowledge is re-

quired to reverse-engineer models. Further, reverse-

engineering is not always necessarily completely suc-

cessful: even if the how (which is doable with a lot

of effort) and the what (which is incredibly difﬁcult

to differentiate from how) are discoverable, the why

is likely not. Additionally, some non-functional re-

quirements as well as timing requirements, may not

be recovered through reverse-engineering.

3.2 The Model is Not the

Documentation

Both anecdotes above effectively refute the “model is

the documentation” myth. As the stories illustrate,

and as we have seen on many other occasions, docu-

mentation of the design of a model that captures de-

sign rationale is a crucial artifact that, ideally, con-

tains the information that makes reverse-engineering

efforts largely unnecessary, or at least signiﬁcantly

easier and more effective. Further, documenting de-

sign during the design process enhances the problem-

solving process by enabling designers to better under-

stand the problem and have a ﬁrmer grasp on different

possible solutions.

The “code is the documentation” paradigm that

existed (sometimes still exists) in traditional software

engineering, is analogous to the MBD catchphrase

that the “model is the documentation”. Years ago,

Parnas (Parnas, 2011) discredited it by arguing that

different views, with different abstractions from de-

tailed code, are needed. The same holds for models.

4 CURRENT SUPPORT FOR

SIMULINK DOCUMENTATION

4.1 Related Work

Academia has shown little interest in documenting

Simulink models. There exist several causes for this

situation. First, the research lacks exciting theoret-

ical underpinning. Second, industry has not shown

much interest. Given the pressures of releasing often

and cutting down on development costs, industry of-

ten lets documentation efforts lapse.

Rau notes some of the common problems with

creating and maintaining software documentation for

Simulink models (Rau, 2002), namely, that it is often

ambiguous, inconsistent, non-existent, incomplete,

and tedious to create. This is attributed to documenta-

tion being a separate artifact from the implementation

in addition to being created at a different time, it being

generally informal and unstructured, with redundancy

between both documents themselves as well as be-

tween documentation and model. Rau then sets prin-

ciples for effective production and use of documenta-

tion in development with Simulink. First, Rau advo-

cates for an integration between a model and its docu-

mentation. MathWorks later provided support for this

principle by introducing a special kind of Simulink

block: DocBlocks allow one to embed descriptive text

in a Simulink model. Further, Requirements Man-

agement Interface (RMI) allows linking to external re-

quirements documents to create traceability from the

model to the requirements, as Rau advocates. In his

own demonstration, Rau uses custom blocks to docu-

ment signals in order to produce the model/subsystem

interface. MathWorks has added ﬁelds for e.g. spec-

ifying units for subsystem ports, but otherwise the

generic Description block property can be used to doc-

ument signals textually.

The next important principle emphasized by Rau

is structuring and formalizing documentation, while

offering developers placeholders to ﬁll in (Rau, 2002).

While Rau does not elaborate this principle, the con-

tents for both SRS and SDD for Simulink models are

discussed in (Bialy et al., 2017). Further, Schaap et al.

deﬁne the (minimal) contents of the Software Design

Description (SDD) for Simulink models and propose

tool support to semi-automate the generation of SDDs

(Schaap et al., 2018).

4.2 Tool Support

Along with the possibility of embedding documen-

tation within a model, the key is the ability to gener-

ate external documents. MathWorks’ Simulink Report

Generator generates reports in various formats from

Simulink models at the press of a button. However,

the default templates offered by the tool only extract

information already present in the executable part of

the model – resulting documents consist primarily of

block parameter tables and are, consequently, of lim-

ited use. Additionally, formatting a resulting report

MODELSWARD 2019 - 7th International Conference on Model-Driven Engineering and Software Development

506

(MS Word document) can be quite difﬁcult. For ex-

ample, formatting tables, heading font sizes and num-

bering, or eliminating unnecessary space between el-

ements such as headers and contents, can be no-

toriously hard. Furthermore, disabling components

(deleting sections) of the template sometimes causes

unexpected behaviour. Lastly, there is no search func-

tionality built into the tool’s graphical user interface

(GUI), which makes developing a larger template te-

dious. To create traceability to requirements, there is

the RMI, but documents must be in speciﬁc locations

relative to the model. Traceability from external re-

quirements to portions of a model is possible as well,

but is even more fragile. While these are the build-

ing blocks for the approach advocated by Rau (Rau,

2002), they do not constitute a practical approach on

their own since the usability deﬁciencies will deter

most developers.

The approach of (Schaap et al., 2018) prescribes a

(customizable) SDD template and provides guidance

on its contents. Developers add documentation via

customized template-prescribed DocBlocks in either

text or RTF format. The reports are then generated via

Simulink Report Generator. The beneﬁt of deﬁning

the structure is consistency across the organization

and less developer effort to produce documentation.

Once the DocBlocks have been ﬁlled in by the devel-

oper, document generation and formatting are fully

automated. Also, documentation of syntactic subsys-

tem interfaces is fully automated using the Signature

Tool (Bender et al., 2015). This automation allows

developers to focus on writing useful contents such

as rationale for design decisions. Since the work of

Schaap et al. proposes minimal content for an SDD,

an organization is likely to want to customize the SDD

template. Customization, however, would present a

tedious task given the formatting issues with the un-

derlying Simulink Report Generator as the report gen-

eration engine.

The tool support for authoring, analysis, and man-

agement of requirements is much better than the pre-

sented tool support for documenting a model’s inter-

nal design. Since Simulink R2017b+, MathWorks of-

fers the Simulink Requirements toolbox. By default,

Simulink Requirements provides a developer with ID,

Summary, Description and Rationale columns for re-

quirements; however, custom attributes can be added

for sets of requirements. In this way, for example,

anticipated changes can be expressed. The require-

ments can then be linked to tests, models and code.

Simulink Requirements allows for requirements to be

expressed using natural language only.

4.3 Templates

Like Rau (Rau, 2002), Bialy et al. (Bialy et al., 2017)

and Schaap et al. (Schaap et al., 2018), we deem pre-

cisely deﬁned content of the SDD as critical to the suc-

cessful utilization of documentation in software de-

velopment and maintenance processes. Our experi-

ence with industry partners clearly conﬁrms this. In

our collaboration with an automotive OEM, we have

witnessed a case where, while the basic structure (ta-

ble of contents) of the SDD was deﬁned, the required

content was not precisely speciﬁed. For example,

the template prescribed that the architectural view of

a Simulink model be included in the model’s SDD.

However, the term was not deﬁned anywhere and no

requirements were imposed on the section’s content,

leading to inconsistent SDD documents throughout

Simulink models of the same controller. Numerous

similar issues lead to an ineffective use of documen-

tation and, ultimately, its abandonment. The incon-

sistency problem caused by the lack of common un-

derstanding of the term architectural view was not

surprising: after all, there exists no single agreed-

upon deﬁnition for software architecture (Garlan and

Perry, 1995). However, we found out that even some

terms that are well rooted and used within the soft-

ware community, were largely misunderstood. For

example, the SDD required rationale for design de-

cisions to be documented. The concept of rationale,

however, was poorly understood among the develop-

ers: many of them mistook it for the purpose of the

subsystem. This is in part due to many of the de-

velopers in the embedded software industry lacking

software engineering background (Bialy et al., 2017).

Organizations ought to document their processes and

describe resulting artifacts within internal documents

(as standards, guidelines, and/or procedures), includ-

ing precise deﬁnition of all relevant terms. In addi-

tion, for example, in the approach of Schaap et al.,

described earlier, the terms and concepts as deﬁned in

a document can be leveraged from within documen-

tation templates and included in the generated docu-

mentation, where appropriate.

5 DOCUMENTATION CULTURE

Recognizing that documentation in Simulink model

development is necessary is only part of the solution

to the problem of unmaintainable Simulink models.

Developing a sustained standard of documentation

that includes conventions and notations that prove

useful in all aspects of the development and mainte-

nance of these models is also necessary. We propose a

Something is Rotten in the State of Documenting Simulink Models

507

culture of documentation as an effective way of main-

taining such a standard.

We intend “culture” here to take on its usual mean-

ing, as a set of shared beliefs, attitudes, values, etc.

within an organization. Because culture is cohesive,

a culture of documentation would allow a belief and

understanding that documentation is just as important

as the artifact it documents to span the organizational

hierarchy. For such a culture to develop, support is

required on several fronts. Change management is

notoriously challenging, and there are some proven

approaches to it (Anderson and Anderson, 2010). In

support of these well documented approaches, we dis-

cuss some aspects speciﬁc to our suggestion.

5.1 Coming from the Top

It is vital that managers emphasize long-term com-

pany concerns with respect to the development of

software intensive products. Consequences of com-

pany software development culture are not as intuitive

as they may be in other engineering disciplines. For

example:

• Managers must foster the idea that quality must

be “designed in” from the start. Too often, man-

agers promote too early development of design

and even code simply because it is so easy to

create software. Creating software in an ad hoc

manner is not the same as creating, documenting

and using a methodical approach to plan and de-

sign high quality software that provides a safe and

dependable product. Early “solutions” often turn

out to be mirages – the closer we get to them the

more we realize that they do not deliver what they

promised, and when they do successfully deliver

on the required functionality, they are likely to

degrade during maintenance simply because they

were not designed with adequate foundations to

start with. A civil engineer, for example, will not

build a structure without ﬁrst performing a slope

stability analysis. Ignoring necessary analyses is

devastating in any engineering discipline, but with

software the devastating effects are often not re-

alized until too late, and then amortized over the

lifetime of the software.

• In the vast majority of industrial cases, software

is not maintained by those who created it. An

awareness must be developed that newcomers will

likely handle the software during its maintenance

phase – and the original developers may not be

available for discussion! In addition, the implica-

tions of software developers having to reverse en-

gineer these artifacts sometime in the future were

documented in an earlier section.

On the technical side, the change in culture re-

quires templates, standards, procedures and guide-

lines to support effective creation, use and mainte-

nance of documentation. We discuss this next.

5.2 Supporting Standards, Guidelines,

Templates

Successfully fostering a culture of documentation re-

quires a policy that enforces the production and main-

tenance of documentation during the software life-

cycle. This policy should impose the existence of

documentation templates, but as we have seen, tem-

plates alone are not enough. While templates pre-

scribe the format and content of the documentation,

they are not nearly as useful if, for example, develop-

ers are unaware of the terminology used in the docu-

ments; the notations to be used; or the process of doc-

umentation maintenance as part of the change man-

agement process. Therefore, internal documents (be

they guidelines, standards, procedures, or a combina-

tion thereof) are needed to precisely deﬁne the devel-

opment processes including the software documen-

tation activities and the artifacts to be generated by

their application. Process documents rarely, if ever,

provide enough detail in the process steps to ensure

that the results of applying the process consistently

achieve the quality attributes desired. There are many

reasons for this. Two of the most important are: i) it

is difﬁcult to document process steps to that level of

detail; and ii) most companies like to leave things less

well-deﬁned so that developers have more freedom to

do what they think is right in a given situation. One

way of combating this that seems acceptable to most

developers, is to be more prescriptive in the content

and format of the generated documentation.

5.3 Rigour

In other engineering disciplines, documentation typ-

ically uses mathematics to specify and describe sys-

tems precisely; unfortunately, this is not the case

with software documentation where natural language

is prevalent. However, natural language suffers from

ambiguity. Many methods for formal speciﬁcation of

requirements exist, for instance tabular expressions

(Wassyng and Janicki, 2003). We advocate the use

of mathematics to make documents more precise and

leverage some advanced veriﬁcation tools. Formal re-

quirements can be automatically checked for consis-

tency and completeness. Crucially, they can be used

as a basis for automatic test generation and for for-

mal veriﬁcation of Simulink designs against require-

ments. In fact, advanced commercial tools exist for

MODELSWARD 2019 - 7th International Conference on Model-Driven Engineering and Software Development

508

automatic test generation and formal veriﬁcation of

Simulink models (e.g., MathWorks’ Simulink Design

Veriﬁer (SDV) and Reactis by Reactive Systems).

5.4 Automate, Automate, Automate

Automation of routine tasks is essential to the de-

velopment and maintenance of software (Hunt and

Thomas, 2002). Proper tools are essential in sup-

porting documentation efforts. Existing tool support

for documentation of Simulink models is not yet ade-

quate. For example, Simulink Report Generator needs

to undergo major improvements to be used as a proper

engine for automatic generation of reports from de-

ﬁned templates. The tool described by Schaap et al.

(Schaap et al., 2018) is an academic tool that lever-

ages Simulink Report Generator and needs to be im-

proved to provide easier template customization as

well as a GUI for, at least, conﬁguration.

MathWorks’ Simulink Requirements toolbox can

also be enhanced. As mentioned before, adding ﬁelds

for anticipated changes would improve the quality

and usefulness of the requirements in preparing a de-

sign that may be more robust with respect to future

changes. Simulink Requirements can store require-

ments only in ASCII text or MS Word. However, if re-

quirements are formalized using Simulink/Stateﬂow,

as Simulink/Stateﬂow models outside of Simulink

Requirements, they can be linked to their textual rep-

resentation in Simulink Requirements using traceabil-

ity links provided by the combination of the Simulink

Requirements and Simulink Test toolboxes. Tests

could be derived using Simulink Test or Simulink De-

sign Veriﬁer (SDV). SDV tests can be imported into

Simulink Test, and could then be linked to require-

ments and designs.

6 CONCLUSIONS

We have presented empirical evidence that industrial

practice demonstrates a need to properly document

Simulink models. The anecdotes we presented may

be few, but they are drawn from more than ﬁve years

of experience working closely with automotive indus-

trial partners on their Simulink models. They are rep-

resentative of what we observed in general. We also

presented the case for a cultural change that we be-

lieve is required to improve both the quality and sta-

tus of documentation in the MBD process in industry.

These changes require substantial resources, as well

as direction and commitment from management. We

believe that the required resources and dedication will

pay off in the long term. As immediate future work,

a systematic approach would examine the Simulink

models documentation practices in the automotive in-

dustry and help deﬁne more precise documentation

requirements. This work would pave the way to creat-

ing effective documentation standards, deﬁning more

concrete actions in implementing the documentation

culture, and developing better tool support.

REFERENCES

Ackermann, C., Cleaveland, R., Huang, S., Ray, A., Shel-

ton, C., and Latronico, E. (2010). Automatic require-

ment extraction from test cases. In Barringer, H., Fal-

cone, Y., Finkbeiner, B., Havelund, K., Lee, I., Pace,

G., Rosu, G., Sokolsky, O., and Tillmann, N., editors,

Runtime Veriﬁcation, volume 6418 of LNCS, pages 1–

15. Springer Berlin Heidelberg.

Anderson, D. and Anderson, L. A. (2010). Beyond Change

Management. Pfeiffer, San Francisco, California.

AUTOSAR (2018). AUTOSAR – enabling innovation.

https://www.autosar.org. [Online; accessed Novem-

ber, 2018].

Barnard, P. A. (2005). Software development principles ap-

plied to graphical model development. In AIAA Mod-

eling and Simulation Technologies Conference and

Exhibit, San Francisco, CA, USA. American Institute

of Aeronautics and Astronautics.

Bender, M., Laurin, K., Lawford, M., Pantelic, V., Ko-

robkine, A., Ong, J., Mackenzie, B., Bialy, M., and

Postma, S. (2015). Signature required: Making

Simulink data ﬂow and interfaces explicit. Science

of Computer Programming, 113, Part 1:29–50.

Bialy, M., Pantelic, V., Jaskolka, J., Schaap, A., Patcas, L.,

Lawford, M., and Wassyng, A. (2017). Software En-

gineering for Model-Based Development by Domain

Experts. In Griffor, E., editor, Handbook of System

Safety and Security, pages 39–64. Syngress, Boston,

1st edition.

uck, D., Elmqvist, H., Mattsson, S. E., and Olsson,

H. (2002). Dymola for multi-engineering mod-

eling and simulation. In Proceedings of Model-

ica, volume 2002. Citeseer. Online at https://w

ww.modelica.org/events/Conference2002/index

html

Garlan, D. and Perry, D. (1995). Introduction to the special

issue on software architecture. IEEE Transactions on

Software Engineering, 21(4):269–274.

Hunt, A. and Thomas, D. (2002). Ubiquitous automation.

IEEE Software, 19(1):11.

ISO (2011). ISO 26262: Road vehicles – functional safety,

International Organization for Standardization (ISO).

Lethbridge, T. C., Singer, J., and Forward, A. (2003). How

software engineers use documentation: the state of the

practice. IEEE Software, 20(6):35–39.

Mader, P., Jones, P. L., Zhang, Y., and Cleland-Huang,

J. (2013). Strategic traceability for safety-critical

projects. IEEE Software, 30(3):58–66.

Something is Rotten in the State of Documenting Simulink Models

509

Parnas, D. L. (1972). On the criteria to be used in decom-

posing systems into modules. Communications of the

ACM, 15(12):1053–1058.

Parnas, D. L. (2011). Precise documentation: the key to

better software, pages 125–148. Springer Berlin Hei-

delberg, Berlin, Heidelberg.

Rau, A. (2002). Integrated speciﬁcation and documentation

of Simulink models. International Automotive Con-

ference.

Sagoo, J., Tiwari, A., and Alcock, J. (2014). Reviewing

the state-of-the-art design rationale deﬁnitions, repre-

sentations and capabilities. International Journal of

Design Engineering, 5(3):211–231.

Schaap, A., Marks, G., Pantelic, V., Lawford, M., Selim,

G., Wassyng, A., and Patcas, L. (2018). Documenting

Simulink designs of embedded systems. In Proceed-

ings of the 21st ACM/IEEE International Conference

on Model Driven Engineering Languages and Sys-

tems: Companion Proceedings, MODELS ’18, pages

47–51, New York, NY, USA. ACM.

Sousa, M. J. C. and Moreira, H. M. (1998). A survey on

the software maintenance process. In Proceedings of

1998. International Conference on Software Mainte-

nance, pages 265–274. IEEE.

Wassyng, A. and Janicki, R. (2003). Tabular expressions in

software engineering. Proceedings of 2003. Interna-

tional Conference on Software and System Engineer-

ing (ICSSEA’03), pages 1–46.

MODELSWARD 2019 - 7th International Conference on Model-Driven Engineering and Software Development

510