Documentation Roadmap

[HalilFocic]

Hello. I would like to contribute to documentation since I dont think it's very organized. Might be personal but I had really hard time trying to figure stuff since my project at work required a lot of stuff that doesn't come out of the box and you had to manually do the digging. My main source or inspiration was the full featured editor by jgraph.

I don't think the mxGraph documentation is really any better but we can for sure take a lot of stuff from them to power our Docusaurus docs.
Storybook provides really good examples but its quite hard to figure out where to look to find the source code you need.

At current moment, I don't know if the priority is on documentation or fixing bugs/adding features. I am open to everything but I think we are losing a lot of users due to bad documentation.

[HalilFocic]

@tbouffard If you think we need to prioritize on featues, just make feature issues and assign them to me, I'll handle it but what I see from Issue list is that we got a really small number of bugs in core, most of them are storybook related. I dont think fixing manhattan connector is more important than docs since really few people will use the connector and a lot of people need proper docs.

[HalilFocic]

I am not quite sure what are the best paths to take here. I can tackle the migration from mxGraph to our docs and once that is finished we can maybe discuss where to take it from here. I would love to see more links on the left side. I dont think a lot of people will connect the dots when they go to "API" page. It has everything but going through it is difficult. I think tutorial should take you from 0 to graph with some features and basic understanding of maxgraph. Current tutorial doesn't do it. So lets migrate the mxGraph docs first and them reorganize and add sections on the left.

You can assign any docs related issue to me and I will handle it when I have the time.

[tbouffard]

Hi @HalilFocic , and Happy New Year! 🎉

To get started, I suggest we move the former mxGraph contents into the documentation and adapt them to the new API. To make the implementation easier, I’ve split issue #345 into smaller tasks. Currently, I’m working on issue #613.

In parallel, we could discuss how to structure the documentation effectively. It’s important to define the types of guides, tutorials, and detailed resources we want to offer. A good starting point might be Diátaxis, which provides a helpful framework for organizing documentation.

Here’s a non-exhaustive list of elements that could add value to our users:

General Suggestions

• Add links to existing examples and/or stories on all pages to illustrate documented concepts.
  Many users have mentioned that finding examples is challenging (some even think we’re missing key examples). Improving this could greatly enhance the user experience.
  For reference, I recently did this in the Codecs page update.

Specific Topics

• Connectors/Edge Styles
  • How to use (including loops), configure, and create custom elements.
• Connector Markers
  • Many additional markers are available in draw.io. For example, I’ve used this one in a project.
  • We could add an example of a custom marker (e.g., a small filled square).
• EdgeHandler
  • Focus on options like enabling bends and other customizations.
• Navigation
  • Pan, fit, scroll, translate, zoom, gestures (with limitations), mouse interactions (link to a story or provide an implementation example).
• Labels
  • Bounds and positions
  • htmlLabels, foreignObject, or SVG text.
  • wrap label into bounds: require htmlLabels. Include wrapping examples.
• Logs
  • Default implementation (no logs), console, Maxlog (require css and show function call to display)
  • How to use a specific logger implementation
  • How to implement a Custom logger: implement dedicated interface + usage
• Shapes + Custom Shapes
  • How to implement and register them.
• Stencils
  • Link to the existing story and draw.io resources.
• Tree Shaking
  • Partial support: migration steps, plugins, and links to relevant issues.
• VertexHandler
  • Options and customizations.

What do you think about these ideas?
Feel free to share your thoughts and proposals.

[HalilFocic]

@tbouffard Happy new year to you as well.

I would have to look up about Diataxis since I am unfamiliar with it. I dont know the every topic you listed here but I can start with the ones Im atleast a bit familiar with.

Also I've noticed that in navigation you say we are limited. I would love to add support for some features and fix bugs if they are present. Thats something I really enjoy, making the software work better. It would also be a plus for our package to work on mobile out of the box.

I'll create PRs with some outline for the topics I am familiar with when I get time to do so.

Cheers.

[tbouffard]

Hi @HalilFocic
I've made some progress in integrating mxGraph content into the maxGraph documentation. I've also started to reorganize the pages with this content.
I've also suggested #625 to better highlight the improvements to the getting-started page you've made in recent weeks. I'd like to hear what you think.

[HalilFocic]

Hi @HalilFocic

I've made some progress in integrating mxGraph content into the maxGraph documentation. I've also started to reorganize the pages with this content.

I've also suggested #625 to better highlight the improvements to the getting-started page you've made in recent weeks. I'd like to hear what you think.

Getting started looks good to me. Nice