Documentation: discussions and milestones

[weedySeaDragon]

Documentation

I'm interested in helping on the project, specifically with documentation. There are obviously lots of small things to be done (fix typos, grammar, clarify, etc.), but I can't find a list of larger goals and priorities. Often when project grows, information and discussions recorded in individual issues and PRs is becoming lost as those are closed. It seems this is happening here and I'd like to help.

I suggest that there be a discussion designated for the overall goals and plans for documentation and some milestones defined.

There may very well be some milestones that the existing team already has in mind. One that I can think of is to have a milestone to "Transform documentation in src/docs into publishable form," which would include ideas from #3315 and #3401 (Use Danger to check if any /docs files were changed; Transform/process all files in /src/docs as needed so they are in publishable form), and updating CONTRIBUTING.md to explain that only /src/docs should be changed and the transformations.

Another milestone might be to ensure that as much reference information as possible can be pulled directly from the code (ex: settings). (This might require some coding standards, obv.)

Having clear, public milestones will also raise the visibility and importance of the documentation.

Thoughts?

(Note: I'm not sure if this is the appropriate place for this. Seems that discussions are not being used here. I don't know if that's because this project doesn't want to use them or if they just haven't been used yet. Someone on the core team can let me know.)

[knsv]

We enabled discussions as topics sometimes span over issues/are not related to a specific issue. It is alright to use discussions!

We have recently increased the amount of time available and have started putting a plan together. This plan is not secret (😄) but is not ready yet. Key areas we have started with:

• modernising the tech stack (typescript)
• decoupling of the diagrams from the core of mermaid
• stream lining handling of the different diagram types
• etc

The short answer to your question is that it makes sense for the project to have a roadmap with milstones guiding the development and the people involved in the project.

[weedySeaDragon]

Excellent. Thanks.

I totally understand the "we have a plan but it's not ready to make totally public yet" :-).
(Been doing software development since the 80s. Done a lot of project management/cat-herding, working with stakeholders and users, etc. And done some OSS. Am a big fan of communicating intent in both code and non-code. It all takes time and effort.)

I'd like to particularly help with documentation, which I mean to include the documentation for project contributors (things like CONTRIBUTING.md, src/docs/development.md, putting mechanisms in place to produce a helpful CHANGELOG.md, etc.) as well as end-user documentation.

When the time is right, let me know if and how I can help with organizing or writing up the milestones or goals for documentation (or any other aspect of the project, really).

And meanwhile I'll keep contributingl via issues and PRs as I'm able.

• Ashley (a.k.a. "weedySeaDragon" here on github)

[sidharthv96]

Hi @weedySeaDragon,

I'm planning to focus on #3397. As the current config evolved over the years, some inconsistencies have crept in. There are a lot of configs in different places, some without proper explanations. I'd ideally want a completely typed config with documentations built in (Purpose, required/not, possible values, default, etc).

I'd love to have a discussion on how to handle this most elegantly in a somewhat future-proof manner.

[weedySeaDragon]

Would be glad to work on this with you @sidharthv96 . (In fact I've been kind of thinking about the same thing re: themes -- how to generate documentation for them that is published into src/docs).

My first thoughts:

1. agree on the ultimate goal for the documentation and work backwards in smaller steps
   • who are the audiences for the documentation? (I know this is fairly obvious, but always worth making explicit to ensure we're thinking along the same lines)
     1. future developers working to maintain or change it (always an audience for stuff like this)
     2. people (developers, probably) reading about the project on the official documentation site (docisfy) or GitHub

flowchart
Old["{Old Config+New Config}"] -->Validate 
Validate --> Transform 
Transform --> InternalConfig

Originally posted by @sidharthv96 in #3397 (comment)

The Validate in your diagram would obv be the key step.

Can we leverage the power of eslint by writing a set of rules? That would mean less code to maintain here. A big win in my book.

Shall we open a new discussion thread?

[weedySeaDragon]

Possible Documentation Milestones

1. Use Vitepress for the project's documentation site New Documentation Proposal #3484
2. Re-organize documentation Documentation restructure and update #2910
3. Ensure settings for each diagram type are documented
   • Find all current setttings for diagrams (theme settings, etc) (depends on work getting themes and configurations cleaned up)
   • Determine the workflow/process for getting the information from the code into the documentation

[emersonbottero]

@weedySeaDragon regarding 3.2

In theory we can link the js/ts files and extract information from there.. (Could even be tests.. so as long as tests passes the docs are correct.. 😅 )

see the example with snippet region from here

[weedySeaDragon]

Being able to quote code looks good, @emersonbottero .

But what I was trying to describe was more about getting the ideas that are in the code. (Ex: which settings are available via css, which are from theme variables; which theme variables are calculated and depend on what other theme variables... etc.)
And how we should get those ideas written down within or connected to the code, then extract that to automatically generate documentation to display on the documentation site.

IOW, I was talking more about the steps before Vitepress: getting the markdown source files created that Vitepress would use.

Right now, the documentation package does some of that: it can extract markdown from within code comments. That's the todo-post-build script. Although files are being moved around ATM to create the monorepo, you can see the comments in packages/mermaid/src/config.ts are extracted and fed into packages/mermaid/src/docs/Setup.md (along with comments from other files).
(Forgive me if you know all of that.)

It may be that documentation does a good enough job and we can keep using that.

(Sorry if I overanswered. Am tired and not good at editing right now.)

[emersonbottero]

Oh.. I didn't knew that..
I'll take a look since I have some knowledge in that too.

[emersonbottero]

Oh.. I didn't knew that.. I'll take a look since I have some knowledge in that too.

Hi @weedySeaDragon I did an POC, a simple one that could show the solution..
take a look in https://emersonbottero.github.io/mermaid-docs/code/modules.html, it was generated from src
and there is an predocs scripts in the package for those...

we can also improve the sidebar menu and add folders and files as menu items. 🤓

[weedySeaDragon]

Nice! Looks like that will do what we want.
👍

[emersonbottero]

@weedySeaDragon take a look again..
please refresh.. 😁

[weedySeaDragon]

I think that @sidharthv96 and @knsv can let you know what files they do/don't want to have there. :-)
(I say that because with the current documentation they've only exposed a few files.)