‘There may be just a stylistic way of writing from back then, and if it was seen as successful, people would use that style in other languages,” Gibson says. ‘I would guess that it’s an accidental property of how the laws were written the first time, but we don’t know that yet.’
Great, so the origin of legalese may be “everyone else is doing it”. Even after millennia, we’re doing the same dumb things…
This post is interesting for a couple reasons. The first is that people asked to write laws tend to fall into this “center-embedding” style of writing. This is important for design system folks to be aware of given design system documentation can loosely be considered a collection of rules–or to use another word, laws. So, if this article is accurate, we’re all predisposed to write this dumb way when we’re creating what we consider to be laws.
The second reason this post is interesting is how it calls out that no one finds this style of writing helpful. Not regular people (duh) and not lawyers. It benefits no one. This is important if only to reinforce the need to write documentation like an actual human being.
When you’re writing a tutorial, remember that you’re explaining things to a non-expert. Avoid jargon, abbreviations, or terms that would be meaningless to a newcomer.
I’d argue jargon, abbreviations and acronyms aren’t helpful for anyone, but hey, I’m happy to go with this rationale if it’ll get us to stop this habit. One thing I think most design system documentation lacks are good ol’ fashioned tutorials. There’s plenty of highfalutin guidance and principles, but not much get-your-hands-dirty, step-by-step tutorials.
I think design system documentation could greatly benefit from them. Things like “designing your first feature with the design system” or “contributing your first component”. These kinds of things have gobs of detail that I think would greatly benefit from a stepped guide.
What fascinates me about this scenario is how a seemingly functional 6-month-old project automatically turns into a haunted forest just by changing hands. Regardless of its age, SVC is textbook legacy software because, more often than not, a question posed about the system, to any team member, results in the same answer: I don’t know.
And this, my friends, is the textbook case for a dedicated design system team. And not only a dedicated team, but a highly stable and continuous roster on that team. Design system teams are an institution of institutionalized knowledge. That is why documentation is so critical–that knowledge needs to get out of brains and into a consumable medium. But everyone on the team could document every hour of every day and there would still be gaps.
A dedicated, stable team ensures that the underpinnings of the system are always known. Becuase the author is right, it takes very little to turn a functional project to turn into a haunted forest.
Figma is ‘always on’, so does this mean that we shouldn’t even try to version? Always live, all the time sounds fantastic and gone are the days of exports and imports and PNGs and PDFs and server storage, but we still have a big problem – maybe we want or need to freeze work.
I’m quite pro versioning–especially if it’s used to its fullest. Versioning keeps a canonical log for changes. It can help designers avoid updating to breaking changes. It does a lot of things that don’t seem all that useful–until it’s absolutely critical.
This post has some interesting ideas, but what irks me is that it doesn’t cover the most obvious one–have actual support for library versioning in Figma.
If there’s one thing I’ve hung my hat on in regards to design systems, it’s the need to reduce a design system’s cognitive load to encourage usage. This article does a good job outlining how this plays out in an engineering context. There’s a lot to like in the post, but this sentence stood out:
Involve junior developers in architecture reviews. They will help you to identify the mentally demanding areas.
This line jumped out at me because it’s a great tip for design systems’ approachability. Junior designers and engineers should be VIP reviewers of documentation and system libraries. Success isn’t praise from the super-senior IC who’s been at the company for a bazillion years. It’s seeing a junior designer or engineer independently get up to speed on the system and use it to create a feature.
In general, the purpose and power of an abstract idea is that it compresses a zoo of concrete examples. But if you haven’t built up that zoo of concrete examples then you miss out on that power.
People like quick wins. They like instant results. This is universal. It’s why humanity cycles through diet fads and get-rich-quick schemes.
This also plays a role in the rise of design systems. Why grind through the work of building everything from scratch when you can pull from ready-to-use components? Make no mistake, the value is deeper than that, but I’d be lying if I didn’t say it play a role. The downside of design systems is that they make fundamentals abstract. And while that equates to greater consistency and efficiency, it comes at a cost. And that cost is the erosion of fundamental skills.
But it’s not all bad. Design systems can also be the solution to this problem. There’s nothing stopping design system docs from acting as an educational resource on fundamental design and UI engineering subject matter. Yes, it’s more work, but it’s important work.