SeaLion case study: Satellite development with Docs-as-Code

SysML v2 comes with a text notation that is causing a lot of discussion. The team from the SeaLion project at Old Dominion University didn't just talk, they did it: the project is a joint CubeSat project involving several US universities. The aim was to implement the development process more efficiently and accessibly using a model-based, text-based documentation system (Docs-as-Code). However, without SysML v2.

SeaLion

On SeaLion I was informed about the recently (2023) published paper Model Based Systems Engineering with a Docs-as-Code Approach for the SeaLion CubeSat Project attention. The aim of SeaLion was to develop a 3U CubeSat with three different scientific payloads and launch it into space. SeaLion was not only intended to fly hardware, but also to test new methods of system development, in particular a model-based docs-as-code approach.

The launch of SeaLion into space was originally planned for 2023, but has unfortunately been postponed several times, most recently in the fall of 2024. Current budget cuts at NASA I wouldn't be surprised if this project also falls by the wayside for the time being.

Docs-as-Code

The docs-as-code approach has long been established in the software world: Developers maintain documentation in Markdown, version it with Git, and Continuous Integration (CI) ensures up-to-date builds and artifacts. The SeaLion team applies precisely this principle to system architecture and documentation.

This served Mach 30 Modeling Language (M30ML) as a basis. M30ML is based on YAML and is therefore both human and machine-readable. The entire system architecture was maintained as code, from requirements and architecture to user stories and telemetry data structures. Diagrams, tables and PDFs were generated automatically.

Here is an example of a user story that is managed as a separate YAML file in gitHub:

id: 4.1
name: Request Satellite Health Data
actor: Ground Station Operator
behavior: request satellite health data packet
rationale: verify/validate AODS sensors & GPS data are within nominal parameters
derivedFrom:
- "2-UserStories/4-RequestTelemetryData.yaml"
example: Request satellite health data packet to verify or validate state vector corresponding to expected orbit profile based on pre-computed orbit propagation model

User Story Request Satellite Health Data in YAML (source: gitHub)

Use cases

The following use cases were addressed in the paper:

1. Stakeholder analysis and requirements elicitation: Requirements are recorded in YAML in text files.
2. Traceability: Automatically generated UML diagrams show dependencies between requirements, user stories and data structures.
3. Technical documentation: Tables and diagrams are generated directly from the models, no redundancy.
4. Review and change management: Git pull requests enable collaborative reviewing of requirements and architecture elements.
5. Onboarding new team members: Users can work with any text editor and only need a brief introduction to YAML

SysML v2 is not (yet) enough

The team has evaluated various modeling languages, including SysML v2. The team decided against this for the following reasons:

• No docs-as-codeEven if SysML v2 supports text notation, it is not intended to be file-based. This means that the paradigm originating from software development is not really well supported.
• Missing tools: The tools available today were perceived as too heavyweight. However, a lot has changed since 2023.
• Too complicatedThe team felt that SysML v2 was far too complicated for this project. Even if many of the language features were ignored, this would still have resulted in a high training effort.

M30ML is an extension of the LinkML-specification. It is lightweight, Git-compatible and YAML-based. This language is not only intended for system engineers, but is specifically designed so that non-engineers can also work productively with it.

The M30ML allows a semantically sound but accessible modeling system. In SeaLion, this was additionally supported by the "Distributed OSHW Framework (DOF)", which maps the assembly structure of the CubeSat. This also includes assembly instructions, interfaces and parts lists.

Tools

The tools used in the SeaLion project are deliberately kept simple:

• Visual Studio Code: The editor of choice.
• YAMLAs a notation format for all architectural elements.
• Jinja2 & shell scriptsFor the automatic generation of documents.
• Git/GitHubFor versioning, collaboration and review processes.
• PlantUMLFor automatic UML diagrams.
• asciidoctor / LaTeX: For output in human-readable form.

These tools had many advantages for an open research project. They are all free of charge (most are also open source) and enable offline work.

Weaknesses

The authors also address the weaknesses, but in my opinion not strongly enough. Unfortunately, it is clear that the academic challenges have been recognized, but not the industrial ones.

• High dependence on team communicationAs so often, communication was difficult, primarily using the options provided by gitHub, including workflow features.
• Subsequent modeling costs timeDecisions made before the model was introduced had to be transferred at great expense.
• Lack of training materialNew members found it difficult to familiarize themselves with the system, as the documentation was minimal and sometimes incomplete.
• Complexity with advanced featuresThe modeling of components and interfaces requires additional tools, some of which did not yet exist.

However, I see many more hurdles for use in industrial practice:

• Scaling: The project consisted of a few dozen artifacts, while industrial projects have to juggle thousands (or tens of thousands) of artifacts
• Features & Usability: To achieve broad acceptance, users expect important features such as embedding images in requirements and user-friendly, dedicated tools.
• Integration: The current tool chain only covers a small part of the V-model; PLM, test integration and much more are missing.
• Roles & rights: The features provided by gitHub as part of this concept are not sufficient for an industrial access model.

These problems are not unsolvable, but not within the framework of research projects. In my opinion, tool manufacturers are in the best position to do so. In software development, many companies have built successful business models on docs-as-code, such as gitHub and GitLab, Read the Docs, MkDocs or Atlassian.

Conclusion: A start on a long journey

SeaLion shows that docs-as-code is also possible in systems engineering. Even if it is unclear to what extent this approach could be suitable for the industrial environment, it is helpful to have a real case study.