Our suggestion for development teams: Use PlantUML to describe or specify runtime scenarios. It has a lightweigth textual syntax (DSL) for sequence and activity diagrams - easy to understand and a lean option for discussing and visualizing activities and processes.
@startuml skinparam componentStyle uml2 actor Admin participant "Import\nHandler" as IH participant "ftp-in" as ftp participant "Optical\nArchive" as OA participant "Data\nManagement" as DM participant "Error\nHandler" as EH Admin -> IH: import( m ) IH -> Configuration: getMandatorCfg IH -> ftp: readFile ftp --> IH: file IH -> OA : storeFile(file) IH -> IH: setupFilterChain IH -> IH: unzip(file) IH -> IH: decrypt(uzFile) alt parse file loop all records IH -> IH: parse record IH -> DM : store client else record error IH -> EH: log record error end else file error IH -> EH: log file error end @enduml
The (rendered) diagram from this textual description is shown below:
Text is easier for developer
Such textual descriptions (a DSL for scenarios) resemble source code - which is often easy for developers to create and maintain.
- use this DSL to sketch and discuss variants of scenarios
- maintain the textual representations in common versioning tools (git, subversion etc), with the established branching and merging options
- in case such scenarios are (later…) implemented in source code, the diagrams might be deleted, which will result in leaner documentation (see tip 6-5 (scenarios for discussion, not documentation)).