Hey everyone!
I've had an idea about using component diagrams in my frontend project workflow. This idea works best with frameworks that rely on components (Vue, React, Angular, Svelte...). I messed with this on a personal project and I really like the benefits it provides, but I would like to hear your opinions or experiences that I might have missed.
Here's a brief example:
Before the start of a project, but after you have some sort of a broad idea of what the project will look like, you create a diagram that looks like this.
This example shows just two components, but the idea is that every component is noted here and that it shows the relationship and the props that get passed down from a parent component.
I have a feeling this would give you a much better idea of what your components will look like at the beginning of the project and keep everyone on the same page. I think it would even help to onboard new developers at a quicker rate.
This would have to be stored somewhere at a repository level so it's easy to access (for developers) and it would have to be maintained throughout the project. This is where it might fail. I imagined this as a guide, so something may be implemented differently during the development stage, but the diagram must be updated with the new information, to keep it up to date. Someone might forget or feel lazy and not update it which renders the diagram useless. I haven't thought of any way to prevent this, so I was hoping someone else might have a suggestion.
Have you ever done something similar? Is the diagram showing too much/little information? If you have any opinions, please share them down below!
Top comments (7)
Your concept of noting down information for others to check on is definitely the way to go.
I cannot imagine to work on a project without having ressources to check on.
I personally feel like your example is a bit too much to maintain consistently across the board. At what point does it become too time-consuming to yield some profit?
In my opinion a well setup Adobe XD/Figma file with prototyping enabled shows/says more than a draw.io diagram, as all the details (click events, different states, styling, ...) can be displayed there.
Thanks for the response!
Yeah, my thoughts exactly about time consumption. That's why I wanted to automate at least a part of it to minimize the need for interaction.
If I got you correctly, do you show all of the states a component can be in? Do you include some more developer-specific details?
Most of the time components are pretty self explanatory, right? I only draw a little ----> with side-information in between components when I feel like this needs extra information to understand. This is pretty rare though.
Design wise:
What I do create though is multiple versions for different states. So I got my
<AwesomeButton />component and this component will have a default, hover and focus state. The person implementing this just needs to look it up and be very strict to follow the example in there. If it says the padding is 5px, just copy what's in the design guide. The design guide should be the source of truth because everyone is following it. If it's flawed, everyone works off of a flawed base.What I like to do upfront before even starting anything:
Create a good old entity relation diagram. Of course this depends on the size of the team but when working with very few people this is the perfect opportunity to brainstorm ideas. This is definitely more of the tech side of things, for example:
What properties should a user have?
How do we store this information in the database? What could the database-structure look like?
First pitch on technology/hosting that we plan on using
and so on
....
This diagram does (in my case) not get updated once we start and only helps for us to be all on the same page when starting out. Often time it also helps to find new ideas when just writing things down together and talking about them.
I feel like I drifted a bit off topic - hope I answered what you asked at least to some degree :D
I see now, I get your point much better now :D
The design stuff and the entity relation diagram make sense, but in our company, our design and backend departments take care of those things so I haven't put much thought into that. But thanks for your input, it's good to look at the bigger picture once in a while!
Of course and thanks for the time you've taken to explain it :D
Automation should be the main way to do this, unless you are working with a really small team and everybody is on board. :)
My first suggestion is to use something like dependency-cruiser, although is can get pretty messy on larger projects, but it can be useful for this. :)
I would also recommend you to check out MermaidJS :)
If you are going to write it manually, this will simplify adding new elements to the graph, either via subgraphs or direct linking.
You could, as a side project or just a task to test out your skills, try to create a script that will parse your code and generate mermaid description. :))
Also, if you are by any chance on GitLab, your ReadMEs and MRs can automatically display that graph. :)
If you don't decide on something automated, just make sure that the whole team has agreed to do it that way and incorporate it into your workflow, otherwise you will get half written graphs that will not be of much use due to a lot of missing information and will soon become unnecessary overhead. :))
Thanks for the response!
This is a lot of useful information, I will definitely try to tackle your suggestion by creating a script and generating a mermaid description, it looks very promising!
Unfortunately, we're on GitHub, but this is would be a great start, nonetheless. At least with mermaid you'd have everything in one place which was my initial idea.
Agreed, there's no way to enforce this if we want good results. :D
I had the same idea. and I needed some kind of diagrams or flowcharts for my complicated projects, especially since we plan the project's structure inside the group and diagrams can be really helpful to share out toughts. but I still couldn't find anything suitable for my problem.