Specman is a WYSIWYG editor for actogramms, which are similar to Nassi-Shneiderman diagrams but incorporate some graphical elements from UML activity diagrams. Specman is designed for the specification of procedural workflows in software systems, and grew out of more than 15 years of experience in software engineering based on standard tools like Microsoft Word, Confluence and UML.
Microsoft Word is an excellent word processor with change tracking (a crucial aspect for iterative / agile development), but control structures like loops and branches are difficult to visualize. UML activity diagrams, on the other hand, are very good at visualizing control structures, but change tracking and diagram layout stability in iterative development are poor. Specman combines features of these tools in a way that has proven particularly useful for efficient, iterative software development.
Specman is a small Java 2D / Swing application packaged as an executable JAR file using Maven. To run Specman, you need a Java Runtime Environment (JRE) version 21 or higher installed. The main class is specman.Specman, and the delivery package includes launcher scripts for Windows (specman.bat) and Linux (specman.sh) that check the Java installation and locate the jar before starting the application. Opening the file anagramms.nsd in Specman displays the following diagram:
A significant graphical difference to Nassi-Shneiderman diagrams is the representation of decision nodes by diamonds as they are known from UML activity diagrams. The original Nassi-Shneiderman notation uses triangles which can make a diagram look cluttered when used repeatedly.
Every structured step in a diagram can be collapsed, to hide the details of its inner structure. The following screenshot shows what the "Two Word Anagrams" diagram looks like when all steps are collapsed:
The requirement in the description of the example is taken from a code kata published on codingdojo.org which perfectly illustrates what Specman and actogramms are made for: up-front design - both structured and change-friendly - rather than "design a little, code a little", which is a widespread antipattern. Check out clean-code-developer.com to see why it’s an antipattern. Writing code directly from the business requirements has a high risk of ending up in spaghetti code even though the task doesn’t sound too complicated at first glance. No big problem in one-shot coding, but a nightmare in iterative development where requirements are constantly changing.
Since version 1.3, the diagram files have a pseudocode-like format which makes them machine-readable e.g. to feed code generators or AI agent based programming pipelines. The file structure follows an EBNF grammar defined in SpecmanModel_V002.g4, which is part of the delivery. It is explicitly designed to also integrate AI support in the process of creating specifications. Using Specman’s autoload mode and its headless sanitizer makes it possible to set up a collaborative environment where the user is working with the WYSIWYG UI while an AI agent is supporting in the background. Specifications are supposed to be designed as both human-readable and technically exact, using a natural but precise language according to basic clean code development principles and the central ideas of Domain-Driven Design. The result is a document with structure and textual content which is perfectly understandable for AI agents.
Specman provides a high-quality PDF export, so that the diagrams can be shared easily with everyone involved in the software engineering process. Reviewers only need a standard tool like Adobe’s Acrobat Reader to open and comment on the exported diagrams. See anagramms-export.pdf for an example of a PDF export of the "Anagrams" diagram.
The yellow highlighting in the screenshot above indicates changes which were made in change mode. Similar to Microsoft Word, e.g. deleting text in change mode does not actually remove the text; instead, it is displayed as struck through with a yellow background as if someone had marked the section with a text marker. Changes in a model are therefore immediately recognizable by everyone. This is a crucial aspect in iterative development where specifications evolve over time.
Folding up a structured step which includes any change marks will cause the unfold-button beside the step number to be displayed in the highlight color of the hidden changes. I.e. even if details are hidden, it is still visible that there are changes in the folded up section.
Since version 1.2.1, Specman supports multiple change sets, which is of interest e.g. if there are multiple change requests to be considered in parallel within a single development iteration.
To get an idea of what real-world specifications look like in Specman, see the bird’s view on a mid-size system usecase specification from ongoing project development.
The complete manual is available at Specman Manual.
For maintainers, the manual process for creating a GitHub release is described in How-to: Einen GitHub-Release manuell anlegen.
Project setup and creating of the Specman Windows installer is described in How-to: Specman Windows Installer.