Provide Documentation

[ricardomatias]

Provide documentation with links to the source code and additional resources. This may allow users to find their way into the toolkit more easily.

Tasks

• Documentation can be found
• Documentation can be searched
• Documentation can be enriched with examples and external links
• Documentation caters towards different audiences (shallow integrators, customizers)
• Documentation separates public API from internals (TBD)
• Documentation is publicly accessible / linkeable via deep links
• Documentation is able to handle cross project boundaries (i.e. diagram-js ➕ bpmn-js)
• ...

See also 2021 assessment of our documentation.

---

Related to bpmn-io/diagram-js#78

Related to forum post

[nikku]

Examples for auto-generated documentation:

• JSDoc to HTML

Examples for custom-made documentation:

• Read the docs

Examples for mixed API docs + custom-made:

• Threejs docs

[bennypowers]

In addition to generating a docs site, please generate .d.ts typings from your JSDoc. This should be a relatively straightforward, publish-time step, although it would provide much value to users.

microsoft/TypeScript#32372

[nikku]

@bennypowers Thanks for the link.

Why would that be necessary? The TypeScript type checker does not consider JSDoc in node_modules?

[bennypowers]

unfortunately not :/

additionally, this could help you generate docs via typedoc (either as JSON to be fed into some other documentation engine, or as html)

[nikku]

Linked your idea here. Valuable input, thanks for sharing.