"We don't have time for this"

Multiple client executives asked me before: "your code seems don't have much documentation, why not follow the best practices?"

Well, best practices have context where they work best. My approach is always a self-describing code. Comments are only for the why, the decisions the code doesn't capture and the occasional exceptional implementations.

And I rarely had not enough time to document due to my focus on what matters. However most of their teams, peer engineers said "We don't have time to document." I get it. But after 20+ projects, the same pattern returns.

Those who say they don't have time to document are actually the ones re-litigating decisions on review boards that were made weeks ago, spending another three hours of everyones time. Then another engineer is about to onboard and the dance starts again.

Why we use that stack? Why not a different one? While the users still can't log-in to their account in an embarassing ratio.

The right documentation doesn't waste time or prolong a project. It recovers the time tax you already pay anyway, just hides in your calendar under meetings.

Then I get a different answer sometimes: "We already have the architecture diagrams."

Great. But they you look and those didn't explain the why. They are not even accurate anymore, the code diverged long ago. A new engineer reads the doc, looks at the code and then codes the wrong solution confused by the two worlds, trapped by trade-offs undocumented, repeating mistakes that shouldn't have been repeated.

If you fix these problems, congratulations, you finally got a viable Tech North Star. A documentation that doesn't just tell what is now, but gives a plan how to go ahead and where are you going. That worth all their efforts.

However, given a boxed version, you would say: "But we build our own North Star."

And yes, you absolutely have to. But do you know what goes in to one and how to structure for effect? A Tech North Star no-one buys into or confused by can even damage ongoing or future projects.

Take my package as a starting point. Keep the structure, adapt the content to your context. Throw away what doesn't fit your organization. Wisdom is human.

But the package gets you to "good enough to build on" in days, not months.