Provide Documentation - Githubissues

ricardomatias commented 9 years ago

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 commented 9 years ago

:+1: so badly

ricardomatias commented 9 years ago

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

matehat commented 9 years ago

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 :smiley:

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 commented 9 years ago

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 commented 9 years ago

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

Diaskhan commented 5 years ago

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 commented 5 years ago

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

Diaskhan commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 3 years ago

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!

adrianschneider94 commented 3 years ago

A little addendum: Typescript support (#481) would make the documentation part far easier -- you would just have to lay out the basic concepts and provide a little example, the rest should be self-documenting...

nikku commented 3 years ago

Perhaps that stops many developers from using the diagram.js altogether.

@ttutisani I'm sure that is the case and we're sorry about that.

Linked in the README are both, complex editors built on top of the tool and a simple editor example. If non of these help you out, it is likely better to look for a diagram editing core somewhere else.

bernardoadc commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

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 commented 1 year ago

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

adrianschneider94 commented 1 year ago

@philippfromme This link leads to a 404.

nikku commented 1 year ago

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

joeskeen commented 7 months ago

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 commented 7 months ago

@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 :slightly_smiling_face:

joeskeen commented 7 months ago

@nikku it was my top priority this morning :wink:

Please review at your leisure.

bpmn-io / diagram-js

Provide Documentation #78