Comment by wolframhempel | Hacker News Reader

Comment by wolframhempel | Hacker News Reader

A lot of good things have already been said, but having worked on similar initiatives within larger banks, here are some of my key takeaways:

- Treat it as a product. Build something that would be appealing to real world customers. Spent time on writing great documentation, making a website that demos the components and advertise them internally. Even if other teams will be forced to use what you build by company mandate, getting buy-in will make your life much easier.

- Write great documentation. Incorporate usage by other teams as code samples.

- Avoid becoming the bottleneck at all costs. If you ship components to other teams, these components won't do all the things the other teams need. This will create friction for the other team and make you a bottleneck in their development workflow. They won't put up with this for long and quickly start working around your library or ditch it alltogether. To avoid this, make sure you continuously allocate some parts of your team to make fast changes and remain responsive.

- Allow for others to contribute back. Teams won't just use your things - they'll extend it. Make sure you have a clear and structured way to incorporate their changes.

- Stay responsive. Embed your developers and designers within the teams using your library. Don't become "the UI team" that bestows the unworthy with an update at their leisure - get close to your "customers", share their wants and pains.

This is all excellent, and I'll add one more sub point to "Avoid becoming a bottleneck at all costs":

- Be backwards compatible. If you need to break backwards compatibility, advertise it widely and put your people towards the migration. Otherwise, only expand the abilities of components, never remove them and only require less, never require more. If you want to remove from what you give or ask for more than you currently require then make a new version of the component (e. g. `components/Button/v2`). Plan for this (e. g. don't ship `components/Button`, ship `components/Button/v1`). Rich Hickey's Spec-ulation talk goes into the principles in some more detail: https://www.youtube.com/watch?v=oyLBGkS5ICk

The reason for this is because your goal is to empower other teams to move faster. The minute that "keeping up to date with the UI library" requires any significant amount of attention you are draining any velocity you added. People will stop (either by not updating or by moving off the library).

> The minute that "keeping up to date with the UI library" requires any significant amount of attention you are draining any velocity you added.

Adding to this: consider that not everyone is reading your release notes weekly or even monthly, and might be coming back to work on something that's been shelved for months.

Having a "breaking changes" page in your docs is incredibly useful when someone is faced with upgrading a project that uses eg v1.1 when your current release is v3.5, as they can quickly find the things that need to change without having to read through 17 pages of release notes.

"Component X was removed in version 3.0, use y or z instead"

"v2.0 changed how configuration works. Instead of always reading the file config.json, there are now several ways to configure, see docs [here]. You can keep using the old file by adding the code: Config.ReadFile('config.json')."

Also, encourage and accept PRs from teams that have unmet needs

Reply on news.ycombinator.com