Provide Documentation

[ricardomatias]

Adding a (self) hosted solution with up to date documentation.

ReadMe.io could be a great option since it's a well built, easy to use system and free for open source.

---

Helpful resources, despite the lack of documentation:

• diagram-js example
• bpmn-js architecture walkthrough, covering many facets of diagram-js and how it builds the foundation of our tools
• source code, including comprehensive
  code docs

[matehat]

👍 so badly

[ricardomatias]

What kind of documentation are you looking for @matehat ?
Your feedback would help us tackle this issue.

[matehat]

Just for a bit of background, I'm incorporating BPMN.js, thus diagram.js in a web app for a project where we need to design these sort of execution flows. In addition to just the graphical modeling itself, we have additional information alongside the business logic data. Things like exactly what gets executed in a task, and some contextual data.

So getting the modeler to work was pretty straightforward thanks to your examples. But getting richer interactions with the rest of our app was non trivial. I got to figure out by browsing the code, that you're using a dependency injection pattern, much like angular, that I need to get a handle on the eventBus object to hook into certain events. But again, figuring out which event I should hook onto for when an element gets selected for example, and what data will be available to me, is a matter of browsing the code and trying out things by hand in the developer console. So the process of learning how to leverage these two libraries in a more complex manner is really slow and painful, but doable.

Another example, I have no idea how I can change the label of a object that's already in the diagram, or how I can add a condition expression to a sequence flow. I will probably figure out, but it's slow and painful.

Unless I'm missing something of course 😃

BTW awesome work guys, despite the documentation thing, the project is incredibly well made.

I would however suggest adding something in there to customize all the defaults that are used throughout, like element sizes, zoom caps, and so on.

[matehat]

To be more precise

• maybe a list of all events (and/or commands that get executed through the command stack) that can be triggered, and what data lives in it.
• the objects that are available by dependency injection, and what we can do with them (their methods). That would include a comprehensive description of the arguments.
• And maybe examples for when you want to register new services, interceptors, command handlers and all sort objects that need to implement a certain interface to be used for certain roles.

[nikku]

Thanks for your comprehensive feedback @matehat. We will try to address these issues in the next milestones.

[Diaskhan]

Very poor docs !

Look at https://jgraph.github.io/mxgraph/docs/manual.html
There are basic docs for creating graph!

The digramjs is mature !
But without documentation is not so usable!

[nikku]

@Diaskhan What do you build on top of this library you need the docs for?

[Diaskhan]

For mxgraph many docs ! And examples!
For example look at this page of examples
https://jgraph.github.io/mxgraph/javascript/index.html
With comparison (documentation, guides) many other people prefer to use mxgraph rather than diagramjs!

[ellyxc]

@nikeee i think a getting started documentation, list of modules and each module capabilities could be helpful for starting point. It has been 4 years and we haven't have any of them.

[adrianschneider94]

Hi,

I totally agree with the previous requests. From what I can see and estimate, diagram-js is (technically) the best platform out there for creating diagrams that have a data structure in the background.
I think there are many many use cases for this library. But without documentation it‘s not feasible. At least not in reasonable amount of time.

Best wishes
Adrian Schneider

[nigel-daniels]

Hi,

I'd love to see some docs that show how to build on diagram-js. The example app is a great start point but there seems to be a gulf between that and something as complex as bpmn-js. For example how to start building ones own version of bpmn-js, how to define a basic modeler, how to add your own elements, rules, modules, etc. A walk through of that process would be super useful right now! I have started trying to build a basic moddel, then add a library based on diagram-js however it's very slow going.
Another example of good docs is the JointJS library: https://resources.jointjs.com/docs/jointjs/v3.1/joint.html

[nikku]

Thanks for sharing concrete use cases and the example of what you regard good documentation. It will help us to improve the documentation in the future.

[ttutisani]

I'm also looking for the diagramming js library, came here, and documentation is non-existent. Perhaps that stops many developers from using the diagram.js altogether.

Not even a getting started page to create a basic diagram for the newcomers?

I will try to figure it out, but if I don't find enough details to build a working app, I will pass.

However, the library seems promising, so thanks!

[bernardoadc]

Not even a getting started page to create a basic diagram for the newcomers?

@ttutisani yeah I agree. I would argue there should be an API doc, but far mor easy and basic is to provide simple examples in the README.

... and a simple editor example

@nikku first of all I'm not even sure I know what you're talking about. I see links to libs built with diagram-js (are those the complex ones?) and in resources, a project for examples. If this is the simple one, you should change the texting, because is confusing:

Advanced
editor - an example showcasing how to build a simple diagram editor

Is it simple or advanced?? As this is an editor, altough simple one, I would call it intermediate.

But what about rendering a basic diagram in a page?

diagram-js
A toolbox for displaying and modifying diagrams on the web.

Now I'm not sure the goal of this project. Is it to create diagrams editors only? I thought I could input some data and render a diagram (with ou without editing capabilities) on a webpage. There's no example to that extend as far as I can see. (BTW, if the main goal IS to build editors, then BEFORE linking to other projects it should mention usage as of that example project. If that is the docs, no problem, just make it clear).

[nikku]

@bernardoadc Not exactly sure what you are looking for.

The editor example is the main entry point to understand what you'll get with diagram-js. Every editor is a viewer, too. So think about it as viewer + additional interactivity.

[bernardoadc]

@nikku I wanted something more straightforward to create "fixed" diagrams (hardcoded), not an editor (but I know this is possible). The interactivity is great, but only if wanted.

PS: I was searching alternatives to mermaidjs

[B-R-Bender]

I agreed, lack of documentation is an issue here.
But I think I can understand why there is no news on this topic from 2015

[philippfromme]

Closed in favor of https://github.com/bpmn-io/internal-docs/issues/683.

[adrianschneider94]

@philippfromme This link leads to a 404.

[nikku]

As of diagram-js@12 we offer comprehensive documentation via type definitions.

[joeskeen]

Love the TS types and documentation. Since there is good JSDoc/TSDoc comments, I think it shouldn't be too much of a stretch to generate a static API documentation site from it and check it into the gh-pages branch for automagical GitHub Pages docs site at https://bpmn-io.github.io/diagram-js . Then from there we could add a couple getting started use case guides. Thoughts?
(happy to contribute)

[nikku]

@joeskeen Absolutely! Just a matter of priorities. Plus, the devil lies in the details (to do it right).

We're open to take a contribution to move this forward. The inofficial documentation can be hosted on any GitHub page 🙂

[joeskeen]

@nikku it was my top priority this morning 😉

Please review at your leisure.