- A MasterClass by David Mamet on screenwriting. Get to the point, characters have a mission, they do it, and they're done. Code is like that. A function does something and it's done. A module does something and it's done.
- Reading a new codebase's tests: it gets you familiar with it really fast. Often, it's even better than the documentation because test functions have these long, descriptive names about what they're testing, and show you strange ways to use the code that often are not even mentioned in the docs. Tests also point to where the party's at. People tend to test the important parts.
- For libraries, I write the library's documentation before writing the code, then write stubs that return the same values for the parameters in the docs, then give it to non developers and ask them to follow the documentation. I don't help them. I just give them an environment ready to use, the documentation, and I shut up and observe their every move. Every eye twitch, every facial expression, every keystroke. I don't correct their "mistakes", I simply take notes of their "mistakes" and put them on "bad developer experience", i.e: my bad. I won't risk polluting raw, pure, data with hints or help because it's not a realistic situation: I won't be with whoever will use it in real life. Doing this shines a bright light on all the things I thought were "obvious" or "normal", all the bad design decisions.
If they could follow the documentation and run the code, I know that developers can. I show it to developers and ask them and see how quickly they're going through it: if someone just takes a glance at the docs and starts writing code without looking again at the docs except for values/parameters, I have impedance matching and the interface/API "makes sense", and they're not being slowed down by weird implementation details that make them go back to the documentation. It made sense enough that they've got it loaded in their head with a glance and they're off using it to do whatever else they set out to do. It won't become something they think about.
This is also valid for applications and UX. I put them facing the application, keep my lips clasped, and observe. Down the line, I think about the millions of hours, and millions of dollars on "Customer Success" or "Customer Support" that will be saved. I think about all we can deliver per person if we're not busy helping people figure out things they shouldn't have needed help for in the first place.
- Commenting intent and rationale behind the implementation to make the XY problem obvious: someone reading might detect that my logic is flawed, or an assumption that is, or has become, false. References to other related issues and information about why it was written that way.
- Logging. Logging. Beautiful loggers.
- Error tracking and performance monitoring. Sort by severity and frequency, then solving that.
- Abstracting but stopping at N=3 or 4. For example, say you're on AWS and writing code that dynamically creates Kubernetes clusters on EKS... You can start with N=1, very concrete, writing code for a Kubernetes cluster on EKS, but your code would look eerily similar to create_eks_cluster. Maybe not you, but there will be a bias towards that, and that bias will carry on and will not only be hard to change, but will also dictacte future code because of inertia. In for a variable, in for a module.
However, if you say, let's support doing that on the three or four major cloud providers, you'll find that even if you don't end up supporting them, your variable names, your functions, your classes, your modules, will not be tied to one cloud provider, and your code will be better.
I say a spectrum, because the pitfall is that some people will want to go higher on the abstraction, and they end up spending way too much time trying to write the most generic code that ends up making coffee. Hence limiting to 3 or 4: even if you don't end up supporting them, the code will be better.
- Documentation. I'm shot in the head. "Future me" thanks "past me" often enough to know that, for another person, documentation will be even more useful than it was for me.
- Tests. Writing them, reading them as stated above.
I'm not surprised. I've had a bad experience with them. Whenever I'd search for a domain name on their site and find it was free, they would take it immediately, and then the price would magically change to something ridiculously expensive.
That was a decade ago, and I've never used them since. For anything.
"Even things that can't go wrong, do" - Troubleshooting Analog Circuits, Robert Allen Pease.
Your perfect plans are drawn around a set of hypotheses and premises, chained unfortunately, some of which I'm not uncertain would be proven wrong the moment you'd try and execute.
I'm also reminded of that scene from the Collateral movie, where the Jamie Foxx character talks about his business plan, the one he's been refining for ten years.
What problems does that B2B AI Enterprise product solve?
For whom does it solve that problem?
How do you know it is a problem?
Do they know it is a problem?
Why is it a problem?
Has it always been a problem and, if not, why now?
How much of a problem is it?
What have they done to solve it?
How much have they put in to solve it?
Are they still putting resources into solving it?
How much will it make/save or what will it change?
Has it worked (has it stopped being a problem) or not?
Why are they dissatisfied with the solutions they have tried, if they have tried any?
If you say Enterprise product, you implicitly target certain Enterprise/organizations, a certain segment. Talking with people in that hypothetical segment is a good start. It helps you with your messaging/language to get "communication impedance matching" if you will. What words are they using to describe the problem/pain? What words trigger a painful reaction or a nervous laughter? Which category uses which language (end user, buyer, etc.)
Realistically, you'll have to try multiple channels and see which ones work best for you.
Being cost-conscious keeps you aware that cheap things cost more, and cost is not only money, but time, restlessness, anxiety, frustration, etc.
If there is a team you know can deliver with a manageable level of technical debt later, you have worked with before, and you can afford their rate, then maybe. If not, you're building a castle on sand, and don't even know if there will be a castle in the first place.
Then, there's the whole cycle period, from talking to customers to development, the smaller the period, the more cycles.
We developed bespoke software for large, and less large organizations, and they were repeat clients, and we were paid many multiples of the rate of people in the U.S or Europe because we didn't just do "development"; we dived deep and transformed their whole models in some cases. They loved it enough to want to involve us with everything, invest, partner, what not.
That level of involvement is rare.
If I wanted to outsource for some reason, I have people in mind, people who were previously on my team for years, people I hand-picked, people I built a company with.
If you want an MVP or something you can just use as an asset for marketing and the first sales, that can deliver some value but that will most probably will be re-written later, I think you can find people like that. However, you're asking abut "outsourcing" to an "internal" team, and that's a bit confusing to me, hence my long-winded answer.
A good problem to have. Now do a Show HN with the link to your website, or you can resubmit the link you shared a couple of days ago as a Show HN, which is better for this.
It'd be useful to be more deliberate with the language/messaging/copywriting you are using, whether in the original link you shared here or on your website.
If you'd like to hear a thing or two, you're welcome to send me an email; I'll reply if it matches the email address you'll put on your HN profile/bio.
Answers that claim that the question is a duplicate, then OP pleading that they have read the several "original questions" but were unable to fix the issue, or they're talking about something else entirely.
People not even fixing your answer but introducing a minor edit. I think I recall someone listed as a co-author or something with zero change (not even a character was changed).
Bullying OP. The darn person tells you their question is not yet answered, and people persist: nope, comment below answered the question, or that it's a duplicate. Bullying or gaslighting someone into denying a technical problem still exists is fucking wild.
I mean, Quora has become absolutely useless a long time ago, but StackExchange has become harder to read. The amount of focus not to register some dip-shit trying to close a thread because they haven't really understood the problem, the problem you are very aware about, and getting the frustration of the OP because they're talking about the very problem you're looking to solve, is just tremendous.
As someone with my background (check profile), I would never.
Recommandation is something. Action on my behalf is something else.
Accountability and attribution matter more than what people think. When law enfoncement and "Justice" get involved, with unskilled people, when the stakes are prison time, a reader may appreciate this comment.
- Reading a new codebase's tests: it gets you familiar with it really fast. Often, it's even better than the documentation because test functions have these long, descriptive names about what they're testing, and show you strange ways to use the code that often are not even mentioned in the docs. Tests also point to where the party's at. People tend to test the important parts.
- For libraries, I write the library's documentation before writing the code, then write stubs that return the same values for the parameters in the docs, then give it to non developers and ask them to follow the documentation. I don't help them. I just give them an environment ready to use, the documentation, and I shut up and observe their every move. Every eye twitch, every facial expression, every keystroke. I don't correct their "mistakes", I simply take notes of their "mistakes" and put them on "bad developer experience", i.e: my bad. I won't risk polluting raw, pure, data with hints or help because it's not a realistic situation: I won't be with whoever will use it in real life. Doing this shines a bright light on all the things I thought were "obvious" or "normal", all the bad design decisions.
If they could follow the documentation and run the code, I know that developers can. I show it to developers and ask them and see how quickly they're going through it: if someone just takes a glance at the docs and starts writing code without looking again at the docs except for values/parameters, I have impedance matching and the interface/API "makes sense", and they're not being slowed down by weird implementation details that make them go back to the documentation. It made sense enough that they've got it loaded in their head with a glance and they're off using it to do whatever else they set out to do. It won't become something they think about.
This is also valid for applications and UX. I put them facing the application, keep my lips clasped, and observe. Down the line, I think about the millions of hours, and millions of dollars on "Customer Success" or "Customer Support" that will be saved. I think about all we can deliver per person if we're not busy helping people figure out things they shouldn't have needed help for in the first place.
- Commenting intent and rationale behind the implementation to make the XY problem obvious: someone reading might detect that my logic is flawed, or an assumption that is, or has become, false. References to other related issues and information about why it was written that way.
- Logging. Logging. Beautiful loggers.
- Error tracking and performance monitoring. Sort by severity and frequency, then solving that.
- Abstracting but stopping at N=3 or 4. For example, say you're on AWS and writing code that dynamically creates Kubernetes clusters on EKS... You can start with N=1, very concrete, writing code for a Kubernetes cluster on EKS, but your code would look eerily similar to create_eks_cluster. Maybe not you, but there will be a bias towards that, and that bias will carry on and will not only be hard to change, but will also dictacte future code because of inertia. In for a variable, in for a module.
However, if you say, let's support doing that on the three or four major cloud providers, you'll find that even if you don't end up supporting them, your variable names, your functions, your classes, your modules, will not be tied to one cloud provider, and your code will be better.
I say a spectrum, because the pitfall is that some people will want to go higher on the abstraction, and they end up spending way too much time trying to write the most generic code that ends up making coffee. Hence limiting to 3 or 4: even if you don't end up supporting them, the code will be better.
- Documentation. I'm shot in the head. "Future me" thanks "past me" often enough to know that, for another person, documentation will be even more useful than it was for me.
- Tests. Writing them, reading them as stated above.
And much more,
reply