Suggestion: Include more explanatory data to views

[TCMiranda]

Hey there! I hope you are doing well.

First of all, thank you very much for the project.
It is incredible what you guys put together here 🙌

Here is my problem:
As a tech writer, I would like to provide descriptions, links, and tags to viewers of my diagrams so that I can explain why I highlighted specific elements of my model.

That would be extra helpful when creating a view that explains increments, such as:

• New features
• Integration with new services
• The design of a specific Epic
• Correlate with the scope of an ADR

All those examples are incremental. In other words, I mean that they add or change a smaller portion of "architecture" to my model. And views are great to highlight them.

With a view, I can select the pieces of components that are useful to explain certain additions.

If I include a description - at the view level - I could provide an extra explanation of those increments that only make sense in the view context, not in the model.

What do you guys think of this?
Thanks

[davydkov]

Hi @TCMiranda! Thank you so much for your feedback and enthusiasm about the project!

I faced similar challenges with other tools, that's why I decided to create something more flexible. I'm also considering architecture as something evolving incrementally.

Right now, likec4 already allows to "compose" architecture from small portions (workspaces) - separate files, no "imports", with IDE support, "ctrl" navigation, find references, validation.
Though I have to say, sometimes I'm struggling with extend and long fqn references, but have no beautiful and simple solution yet...

For example, I have ("kind of"):

📁project
  📁feature1
     feature1.c4
     feature1.mdx
  specs.c4 
  model.c4
  index.mdx

I keep documentation separate, but next to likec4 model, use existing tools to generate pages with embedded diagrams (as I did for likec4.dev).

Do I understand you right - do you mean view descriptions (like view property)?

views { 

 view some {
   description: "
     ........
   "
 }

}

Or do you mean element/relation?

views { 

 view some {
   include element {
     description: "
       ... override just for this view ...
     "
   }
 }

}

Can you share your vision?

[TCMiranda]

Hi @davydkov!

Your project organization makes sense. I saw your sample project, and I definitely see how that .mdx + diagrams would fit together for a feature reference, an ADR, etc.

But for my use case, I believe that having the information inside of LikeC4 would be more effective.

1. The model is a way to create structured data.
2. I'm deploying diagrams to a web-app where they could be seen out of context.

Let me explain each one of those.

1. The model is a way to create structured data.

By using LikeC4, I have access to the structured data built from the model and views. We have various tools in the model part like tags and links, but we don't have them in the views part, limiting what we can do by parsing the data structure.

What I have in mind is similar to the first example you gave:

views { 
  view some {
    #tag #epic-123
    link my.project/epic/123
    description "
      Highlights new components introduced to 
      the backend to support Epic #123
    "
  }
}

I know the new info wouldn't appear in the export/codegen. That's fine. If it goes to the LikeC4ViewsData it would already create the opportunity to deploy custom solutions with the new data.

2. I'm deploying diagrams to a web-app where they could be seen out of context.

In my case, diagrams will be shared with other tools, such as Notion, Jira, or Slack.
To be able to do so, I exported diagrams to react.js, and parsed them to generate a simple web-app where the route links to the viewId. You can imagine a simple web-app where if you hit /#foo it opens the diagrams named "foo".

Even though the links to those diagrams are in the appropriate place (like I said, on Notion or Jira for example) I believe it would be beneficial to include more information to this web-app I built to share them. If we had a way to define tags, links, and descriptions to views, I could improve this page with backlinks, and a better description to be used on rich previews or just rendered on the page.

Let me know if that makes sense.
Thanks!

[davydkov]

Ah, got it! I update language parser and release later today or tomorrow
Subscribe to #240

[davydkov]

Hey @TCMiranda, I just released 0.31.0
Can you try it?
Supports exactly:

views { 
  view some {
    #tag #epic-123
    link https://my.project/epic/123 // <- here is the only difference, link should be absolute
    link https://some-other-link

    description "
      Highlights new components introduced to 
      the backend to support Epic #123
    "
  }
}

[TCMiranda]

Awesome!! I'll try it out and get back to you soon 😊

[TCMiranda]

Worked perfectly ❤️