I found a great meme on Reddit that made me think of software documentation (probably because I think a lot about good documentation and communication). It can be so hard to know the context that the audience will have when they read something, and I think it’s especially hard to know what can be “too … Continue reading "Documentation for an unknown future"
TLDR: Documentation should be readily available. Plans should be written down, linked to tickets, and tickets linked to code via commit messages. This applies at all scales: global infrastructure, a single application, or a single package within a codebase. “Why”. It’s the eternal question. Take a minute to consider the old story about the three … Continue reading "Why’d they do that?"
This post talks about different aspects of creating a GraphQL API: Schema design Technical elements SDLC Schema design GraphQL represents an abstraction which maps user queries onto code in the backend application, and the code pulls data from a source of truth. This mental model is important for designing a schema, because the abstraction should … Continue reading "How to design a GraphQL API"
I point out in the intro to Technical Debt that development has changed over the years. A core theme of the change is that computers used to be expensive and humans were cheap, and then this relationship reversed where now humans are expensive, and computers are cheap. (I’ll lovingly ignore the easy jokes about sky-high … Continue reading "Interfaces, abstractions, and developer productivity"
There’s a book by Stephen King, called On Writing. I have a lot of respect for Stephen King as a creator. This makes me love the book because it is a great explanation of the process of writing, and his process has obviously produced results for him. Also, it is also a book about how … Continue reading "On Writing…an RFC"
I have a core memory of a meeting I was once in. We were thinking about the design of a system, and I happened to have made a simple diagram before the meeting for another reason. It was a reallysimple diagram — literally three boxes in a row. A few minutes into the meeting, it … Continue reading "Draw a picture"
There’s an old story about Steve Jobs holding a meeting for a product that was filled with bugs and wasn’t working for the users. He asked “what is this product supposed to do?” and when someone responded by telling him about the features, he said “then why isn’t it doing that?” I’ve always appreciated this … Continue reading "Is it working?"
Doing code reviews is mostly about spending thoughtful time reading code. Sometimes people focus on what things should look for during a review, and there are plenty of suggested checklists out there, or you can look at other code reviews among your team and make a checklist by paying attention to the patterns. This one … Continue reading "How to review code written by an engineer better than you"
I’ve noticed I seem to have a different take on politics and people than most people do. I think there are a few books that I’ve read which have shaped my thinking. I wasn’t necessarily trying to learn about politics when I read them, I didn’t read them in any specific order, and they’re not … Continue reading "Politics and people"
I had a discussion at work today where we were adding some fields to a model, and we were talking about whether it should be split into a separate data model. This made me wonder what type of guidance there was out there in the universe. Turns out, there’s not much. I searched around for … Continue reading "When to split a data model"