ManifestoPeopleGithub

The Developer Experience Manifesto

How to build amazing tools, that are productive, empowering, simple, and make developers happy.
The ManifestoEdit on Github

What do I gain by following this manifesto?

Best practices

That you should know while building developer tools

A convenient standard

That you can apply for your developer productivity teams

Encourage discussion

For continous improvement and focus on applied productivity

Who is behind this manifesto?

Dotan Nahum

Founder @ Spectral
One thing that makes software engineering special is that we can fabricate tools out of thin air, to empower other engineers around us.

Uri Shamay

Founder @ Spectral
Developer experience should get a better exposure. There are principles, practices, and eventually it is a craft that we should all share.

Igor Davydkin

Tech Lead @ Climacell

Lee Briggs

Community Engineer @ Pulumi
If you’re asking your developers to learn a whole new tool to get their job done, you’re handing them a problem, not a solution.

Avi Perez

Head of Backend Engineering @ Wix

The Developer Experience Manifesto

01

Keep it responsive
Apply UX response time principles to DX
Apply UX principle to DX: 100ms for instant feel, 1s for keeping flow of thought, 10s for avoiding context switch
Response Times: The 3 Important Limits
Don't hold up developer services
Many development services are metered by the minute, and time here is literally money
Remember that you might participate in a feedback cycle
Tools that you build may be used as part of other tools, try to respect the constraints of such other tools (composition is a good thing!)
If you can't make it responsive, make it feel responsive
Software may have heavy update cycles, however downloading over night or creating a patch update tricks us into feeling that it's fast

02

Keep it simple
Focus on principles and not details
Continuously seek where you can eliminate "required knowledge" from successful usage
Follow the pit of success
Success is often portrayed as hard as climbing a mountain. Great experience should feel effortless, like falling into a pit
Avoid bloat: keep only the deps that you need
When adding dependencies, make sure you have a process to remove or modernize old ones, so that you can avoid bloat
Accept that developers are lazy (a good thing)
Make the introductory tasks trivial and advanced ones simple
Keep your sizes under check
Size is often a lead indicator of complexity - binary size, install size, download size, and more; make sure that what you deliver is free of extra bloat

03

Work with humans
Offer help and contextual help
Depends on the platform, create the appropriate just-in-time help: manpages, help screen and autocomplete
Manpages (Wikipedia)POSIX formatBash autocompletion
Create and maintain live examples
If applicable: a good practice is to keep an /examples folder in your Github repo, or live Codepen examples for other cases
Have best in class documentation
Have purpose built documentation for your tool, or even a website
Maintain visible context
Offer version and other contextual information to send when communicating to a colleague
Output simple error messages
When communicating errors and exception cases, use simple language, and offer a link for extra help if possible
Respect SemVer (or similar)
Have predictable version and change policy that would not surprise people

04

Work with machines
Allow for pluggability, extension, and composition
Where possible make your tool pluggable, open for extension, or composition (see the UNIX philosophy as one example)
Respect the operating system
Don't ignore common operating-system principles. Such as text on STDOUT, errors on STDERR, or no emojis on Windows (yet)
Have parseable output
A tool conversing well with humans, should converse with machines as well. For that we need predictable, formatted, and typed output
Support configuration in many ways
Accept arguments or configuration though flags, environment variables and/or configuration files

05

Plan your architecture
Keep commands flexible, structure predictable
When building CLIs, set up an architecture for commands, with a predictable grammer (noun verb - `post create`, or verb noun `create post`)
Don't do too many things
Similar to other software systems, keep your tool under checks and balances. Identify when it needs to split into several different tools
Enable testability
Sometimes your tool will be a part of a testing suite. Make sure you play well in that scenario - the best way is to dogfood.
Model into core and interfaces
Make sure you have a core that can be wrapped and used in many different ways. Have a clear API for that, for example, so that you could (if you wanted) support plugins.
If possible, use existing work
Some communities already have starters, kits, and boilerplates. Find the good ones and start from there

06

Be considerate
Respect the hardware you're running on
Be mindful of the kind of hardware you are running on, or will be running on. What are the limits or what is already in stress? RAM (for example, Raspberry Pi), CPU?, network?, IO?
Respect the user's troubleshooting time
Offer logging with levels (debug, verbose, info, warn, error), or a good debugging story in general
No tracking or spying
Try your best not to intentionally track or spy on end users, especially if they are developers which deal with sensitive data, naturally
Offer more convention over configuration
Respect your users by offering sane and safe defaults, by convention. With that, do give ways to override with configuration
Don't break existing things
No body likes a tool that installs and breaks a few other tools afterwards. Try not to do that and be mindful of what you could break, or package your tool in a way that can break nothing (Docker container)
Try not to surprise your users
Software updates can be one nasty surprise if not done right. Let your users know about updates, if possible offer to opt-into update risk levels (e.g. stable, beta, canary)
Manifesto