Bundle a README - Sysand Index Documentation

Sysand Index presents a bundled README.md as the project README on the project page. Use it to describe what the project is, what it contains, and what users should know before using it.

When you run sysand build, a README.md file located next to the .project.json and .meta.json files are automatically packaged with the built .kpar file.

project-directory/
  .project.json
  .meta.json
  README.md

README.md files are expected to contain Markdown. See Markdown support for the supported Markdown syntax.

What to Include¶

The README is the first thing visitors see on the project page, and it is the piece of documentation users are most likely to read before deciding whether to depend on your package. Use it to explain how to get started, walk through how the package is structured, and share anything else users should know.

Most package READMEs benefit from covering:

What the package is — one or two sentences naming the modeling domain and the kind of elements it exposes (parts, requirements, libraries, templates), and what problem they solve.
How to start using it — the sysand add command for adding the package as a usage, plus a minimal .sysml snippet that imports something useful from it.
What’s inside — a short tour of the top-level packages or files so readers can navigate the model.
Compatibility — the SysML v2 or KerML release the package targets, and any required dependencies beyond the OMG standard library.
Where to get help — a link to the source repository, issue tracker, or contact address for questions and bug reports.

Tips¶

Lead with a one-line description. Many readers skim; the first line below the heading should communicate the package’s purpose on its own.
Show, don’t tell. A short import snippet is more useful than a paragraph describing what the package exposes.
Pin compatibility precisely. Naming the SysML v2 release identifier and the libraries you depend on avoids surprises when the metamodel evolves.
Link out for long content. Tutorials, design rationale, and full API references usually live better in the source repository than in the bundled README.