392 private links
relevant questions about to include anti-patterns in the documentation. Note these questions are also pertinent .
- How much is the component or pattern being used?
- How often are people looking for it in our design system?
- Is there an opportunity to make it less bad?
Including bad practice in design systems gives us an opportunity to call it out: it's the perfect place for alignment of our understanding or opinion of what constitutes bad practice.
I don’t subscribe to the idea of purely “descriptive” design systems - ones that simply systematise existing UI, regardless of its usability and quality. Design systems have a responsibility to mitigate - and certainly to not proliferate - bad practice.However, design systems must also acknowledge the reality of the context in which they sit. If problematic components and patterns are being widely used, then our design systems can play an important role in discouraging further uptake, raising awareness of their issues, and offering risk-mitigation advice and alternatives to consider. As with most design system concerns, there’s no blanket solution here. But I hope these considerations will help you the next time you’re faced with this question.
Why don’t we approach guidance and documentation as modular parts of our systems, the way we do with everything else?
For example: “Buy this book” not “Buy This Book”.
This is important in button documentation, guidance on links, content A-Z styleguide, developer documentation in GitHub, Storybook or design libraries in Figma or Sketch. Design systems seek to increase efficiency via common solutions that can be maintained centrally and reused in multiple places. We can do that for documentation too.
We can create the guidance in one of those places and link to it. This is more maintainable, but forces people to go to another place to get all the information they need to complete their task.
Documentation has variants too: in the design libraries, we may simply tell people to write calls to action in sentence case, but in the content styleguide, we may want to explain that sentence case is proven to be more readable most of the time. So already we have 2 variants: rule and rule with rationale. As more tools are used for different purposes, the documentation get more variants.
It's common to have multiple documentation tool, so we need a way to plugin our common documentation to every one of them. So the author is working on such tool that can deliver specific documentation variants.
An alternative to Notion
A way to document a web component (an element manifest per web component).
This seems to be a new version.
Starlight has the best core web vital in A11y and SEO compared to MkDocs, Sphinx, VitePress, Nextra, GitBook, Docusaurus, Docsify.
I used to be on a team that was responsible for the care and feeding of a great many Linux boxes which together constituted the "web tier" for a giant social network.
At some point, I realized that if I wrote a wiki page and documented the things that we were willing to support, I could wait about six months and then it would be like it had always been there. Enough people went through the revolving doors of that place such that six months' worth of employee turnover was sufficient to make it look like a whole other company. All I had to do was write it, wait a bit, then start citing it when needed.
One near-quote from that page did escape into the outside world. It has to do with the "non-compliant host" actions: "Note: any of these many happen without prior notification to experiment owners in the interest of keeping the site healthy. Drain first, investigate second."
So the author created a list of actions; methods to apply for any given events.
Hyping yourself is about accurately explaining the value that you contribute. It’s about saying, “Here are all my accomplishments; here is what I’ve been up to; here are the ways that I’ve been growing and will continue to grow.” You demonstrate to others why you’re worth it and you show up with the receipts to back every claim you make.
Keep a Hype doc for it.
A Hype Doc is a running list of all your accomplishments and successes. It’s a place where you keep track of your growth, and regularly jot down the things you’re proud of doing.
It includes: technical work completed, projects led or contributed to, mentorship and development, leadership opportunities, blog psots and talks revelant to your work, involvment in recruiting and interviewing, valuable contributions to discussions, kudos and feedback from others, significant moments of growth or learning.
Update it regularly (weekly?), it should be easy to edit and can be shared to managers.
Si je crois fermement que les "Leads produit" d'une organisation doivent cultiver leur capacité à naviguer dans le flou, c'est-à-dire accepter un changement permanent, c'est bien à eux que revient l'obligation d'apporter de la clarté dans ce flou, une direction, une vision.
Et il y a un outil nécessaire pour ça : l'écrit.
Les articles sur Eventually coding permettent de se constituer un patrimoine, de prendre du recul, de mieux partager l'information dans une équipe distribuée sur plusieurs pays et donc asynchrone.
Toute personne à partir de Senior doit être capable d'écrire pour articuler document de design, stratégie et vision.
Les documents de design: l'ensemble des descriptifs sur un sujet. Ce sont des documents concrets qui décrivent l'usage actuel d'une technologie dans notre contexte.
Les documents de stratégies (ADR, RFC, Roadmap). Ce sont des écrits qui sont là pour clarifier, pour donner un guide de conduite par rapport à une technologie. Une stratégie est souvent le résultat de discussions contradictoires qui a vu l'équipe s'opposer. Une stratégie est là pour mettre en lumière les compromis et une décision. Le document exprime donc une opinion, à l'inverse des docs de sign.
Les documents de vision (North star document, engineering principles, manifesto, technology radar, engineering blog posts, ...) pour montrer une direction à plusieurs années dans le futur.
Stratégie ou vision ? Parfois la frontière est fine. La différence porte bien souvent sur l'échelle de temps. Une stratégie s'exprime pour les 6 prochains mois, une vision, c'est pour les prochaines années.
Comment démarrer?
Commencer par écrire plusieurs documents de design sur l'existant; puis regrouper les documents de design par thème, détecter les questions ouvertes et les contradictions, faire émerger des stratégies; enfin regrouper les stratégies par thème, projeter les impacts dans le futur.
Le Story telling:
L'enjeu c'est de trouver les problèmes à résoudre et de proposer des solutions. Les documents mentionnés ci-dessus ne vont pas suffire, mais, s'ils sont bien faits, ils vont vous permettre de créer le storytelling nécessaire pour une bonne promotion, et plus tard pour une bonne conduite de changement.
Documentation matters
Good documentation is more than just nice to have—it's a powerful way to spread knowledge. For development teams, clear documentation keeps everyone aligned, helps make decisions visible, and ensures no one has to reinvent the wheel when new people join. For users, it saves time. Poor documentation, on the other hand, leads to confusion, support tickets, and more work for everyone involved.
... all common and good tips. They are generics and I don't find anything actionable though.
A better man page online
A TLDR ui in the browser
One of the most prolific contributor on the Astro documentation 👍
They insights are awesome for all devs.
These are great programming and code patterns
Wow, it reminds me Telescope of neovim.