Saw this on Hacker News today. Good stuff! It seems like you’re open to PRs with format and spelling fixes [1][2]. At a scan it looked like a lot of the fixes from the .doc conversion are needed from the section “EASY DEVELOPER EXPERIENCE WINS” through the conclusion. I was starting to volunteer some fixes but it frequently isn’t clear what the desired formatting should be. If you’d be willing to add the .doc to the repo, I’d be happy to use that as the target format and offer fixes through PRs.
[2] “As of October 2023 I'm still working on porting the book content into markdown. Everything is in there (via a .doc to .md auto-converter) but the formatting is all over the place and needs a lot of cleanup still, apologies for my mess in the interrum!”
Hi Zach,
Thank you for writing this book. I think it can help increase the pace of innovation.
Section 3.4 "Testing" is written with the implicit assumption that the reader understands why a startup needs to do some testing. Unfortunately, in my experience, some startup CTOs need to learn this. I have seen some make critical errors like un-staffing testing or migrating to a Service-Oriented Architecture without integration tests. How about enhancing "Section 3.4 Testing" with information on why testing is a necessary part of the software engineering process?
I think it would be good to teach the reader:
The function of testing in the software development process is to catch problems earlier in the process, when they are cheaper to fix. Compare the costs to fix a problem while coding, in CI, after code review, in production. Use this to introduce the terms that show the point in the development process where the test runs: "release" test, "continuous integration" test, and "manual" test.
Signals that the team is underinvesting in testing work
production incidents
increasing bug count
accumulating tech debt
reducing engineering velocity
worsening engineer morale
A prioritized list of what kinds of tests to set up
Manual tests when the product has few features.
End-to-end happy-path feature tests that gate releases. These prevent production incidents.
Integration tests. A team uses integration tests to make sure that other teams don't break their system. Without such tests, every team must spend energy keeping aware of changes all other teams are making, so they can catch breaking changes early. Integration tests become important once the company has engineering teams with separate standup (status) meetings.
Unit tests.
Write good unit tests for any code that has ever had bugs, even if those bugs only occurred during initial coding. Assume that code that handles dates and timezones has bugs until it has full coverage.
For code that has a complicated API, write a single test, with literal input and output data. This test teaches future readers about the shape of the data that the code accepts and returns.
Tests are excellent documentation. They never get out of date. They teach readers how the system actually works. Engineers spend most of their time just figuring out how the system works. Therefore investing in testing pays dividends in developer velocity.
Define the terminology of testing.
a "unit test" (already defined in the book)
an "integration test" runs code that is normally deployed separately and makes them talk to each other. A test that mocks all of its dependencies is not an integration test.
a "feature test" pretends to be a user and actually uses the feature. For a web app, this test runs the app in a browser and clicks buttons and checks for correct changes to the page and correct changes to the data in the backend.
a "test" that runs before deployment
a "check" or "monitor" runs on production, after deployment
...
Monolith testing is cheap and fast. Service-Oriented Architecture uses many deployment units, so unit tests can cover very little code and most tests must be integration tests, which are far more complicated and slow.
Flaky tests harm engineer velocity and morale. Therefore, put someone in charge of getting flaky tests fixed.
Test Dev UX is important. When tests are easy to run and run fast, people write more of them and will fix flaky ones faster. Invest in making tests easy to run and fast on engineer laptops.
Systems with no tests are "legacy" systems. Only the original authors can safely modify them. If the original authors leave, then the new people must add tests before they can safely add features or fix bugs.
Some engineers love to clean up tech debt and will do it eagerly when such changes are low-risk. Test coverage reduces the risk of all code changes, especially code cleanups. Therefore, investing in test tooling can allow your startup to benefit from these instinctive code cleaners.
If a system is hard to test, it will be hard to deploy and manage in production. Follow KISS and YAGNI in deployments and reap the benefits in devops and testing.
Thanks again for writing this book. I hope these suggestions can help improve the book.
Try and define the idea of "standard" -- where many companies use the title in the same way to represent the same sort of work, vs "non-standard" which is more likely to exist at a startup where people where multiple hats. Non-standard roles requiring additional thought/effort into how to write a JD and how to interview/qualify for.
"Standard" roles
Frontend engineering - primarily building UI flows
The idea of the “product focused engineer” I think, as a phrase, assumes that some engineers can think about product and some can’t. My hypothesis is that, for the most part, that’s not actually how the world works. Individuals have different interests and passions, and it's when you align the passion of the individual with the problem when you get the output that we all think of as the “product focused engineer.” Said another way - if the person is passionate about the business problem, and they’re empathetic with the user, they’re far more likely to spend time using the product as a user and find the bugs/opportunities to accelerate product quality.
Hi Zach
I have just read the first quarter yet but I really like it. Since I prefer audio books though to listen while computing, I created one with OpenAI tts-1-hd. I had to split the file in chunks and merge it but the end product sounds quite nice. Just listened to the first few minutes. I could upload it here if you want but wanted to ask first. As you also sell the book on Amazon it would also be understandable if you don't want that. Just let me know.