Don’t document the obvious: I see too many documents that contain sentences like “Name field - contains the name”. Tell me about what I may not know - restrictions on characters, how these are sorted, what if someone doesn’t have a first name, etc. Gregor Hohpe

The core conflict of developer tools is Abstraction vs. complexity Jean Young https://future.com/the-case-for-developer-experience/

Given the right documentation, self-service API integration should come naturally, right? What is the proper documentation though and who defines that? Working with teams to reduce the problem to a “set of questions” that the docs must answer, can help you move towards self-service.

Creativity comes from constraint.

Only three things happen naturally in organizations: friction, confusion, and underperformance. Everything else requires leadership.

‘Who’ questions to ask when leading change: The included: Who else could be or needs to be included in what I’m doing? The informants: Who has done things like this in the past that I can lean on for support? The advisors: who could I get advice from or interview to get more insight? The creatives: Who comes from a different field of work, and could add a creative angle to my change?

An important quality of API design is minimalism, also called #orthogonality. This is a quality shared with programming language design as well. Adding new terms or concepts complicates the design. It adds rules, exceptions, and quirks, thus making it harder to learn. An example is the famous “verb in the resource name” dilemma.

There are three perspectives in software development that are not well aligned: academia, thought-leaders/influencers and the work being done in practice. Jean Young

I prefer not to manage the plan of a project in which I am also responsible for the content and the execution. This is a conflict in responsibilities. F.e. both project manager and solution architect.

When balancing between abstracting complexity away and empowering developers, I ask: What’s their goal? How might we reduce the risk of error? What parts of the current experience do developer enjoy the most? What parts are mundane and tedious?