How to Document Simulink Model: Best Practices and Examples

To document a Simulink model, use Annotations to add text descriptions directly on the model canvas, and fill in Model Properties like 'Description' and 'Author' for metadata. Additionally, use Subsystems with descriptive names and comments to organize and explain parts of your model clearly.

Syntax

In Simulink, documentation is added using several features:

• Annotations: Add text boxes anywhere on the model canvas.
• Model Properties: Set metadata like 'Description', 'Author', and 'Version' via the Model Explorer or Model Properties dialog.
• Subsystems: Group blocks and add descriptive names and comments.
• Block Comments: Add comments to individual blocks.

These elements help explain the model structure and purpose.

matlab

open_system('simulink');
% Add annotation example
add_block('simulink/Commonly Used Blocks/Annotation', 'simulink/Annotation1');
set_param('simulink/Annotation1', 'Text', 'This is a sample annotation');

% Set model description
set_param(bdroot, 'Description', 'This model simulates a simple control system');

% Add and rename subsystem
add_block('simulink/Commonly Used Blocks/Subsystem', 'simulink/ControlSubsystem');
set_param('simulink/ControlSubsystem', 'Name', 'Control Loop');

Example

This example shows how to add an annotation, set model description, and rename a subsystem for clear documentation.

matlab

modelName = 'docExampleModel';
new_system(modelName);
open_system(modelName);

% Add a Gain block
add_block('simulink/Math Operations/Gain', [modelName '/Gain']);
set_param([modelName '/Gain'], 'Gain', '5');

% Add annotation
add_block('simulink/Commonly Used Blocks/Annotation', [modelName '/Annotation1']);
set_param([modelName '/Annotation1'], 'Text', 'Gain block multiplies input by 5');

% Set model description
set_param(modelName, 'Description', 'Example model demonstrating documentation');

% Add and rename subsystem
add_block('simulink/Commonly Used Blocks/Subsystem', [modelName '/Processing']);
set_param([modelName '/Processing'], 'Name', 'Processing Unit');

% Save and close
save_system(modelName);
close_system(modelName);

Output

Creates a new Simulink model named 'docExampleModel' with a Gain block, an annotation describing the block, a model description, and a renamed subsystem called 'Processing Unit'. The model is saved and closed.

Common Pitfalls

• Not using annotations or comments, making the model hard to understand.
• Leaving default block and subsystem names, which are not descriptive.
• Ignoring model properties like 'Description' and 'Author', losing important metadata.
• Overcrowding the model canvas with too many annotations, causing clutter.

Always balance clarity with simplicity when documenting.

matlab

%% Wrong way: No documentation
modelName = 'noDocModel';
new_system(modelName);
open_system(modelName);
add_block('simulink/Math Operations/Gain', [modelName '/Gain']);

%% Right way: Add annotation and description
set_param(modelName, 'Description', 'Model with proper documentation');
add_block('simulink/Commonly Used Blocks/Annotation', [modelName '/Annotation1']);
set_param([modelName '/Annotation1'], 'Text', 'Gain multiplies input by a factor');

Quick Reference

Use this cheat sheet to document your Simulink model effectively:

Feature	Purpose	How to Use
Annotations	Add text notes on model canvas	Right-click > Add Annotation or use add_block('simulink/Commonly Used Blocks/Annotation') and set_param
Model Properties	Set metadata like description, author	Model Settings > Model Properties or set_param
Subsystems	Group blocks with descriptive names	Right-click blocks > Create Subsystem, rename with set_param
Block Comments	Add comments to individual blocks	Right-click block > Properties > Documentation tab

Key Takeaways

Use annotations to add clear text notes directly on your Simulink model.

Fill in model properties like Description and Author for metadata clarity.

Rename subsystems and blocks with descriptive names to improve readability.

Avoid clutter by balancing the amount of documentation on the model canvas.

Consistent documentation helps others understand and maintain your model easily.