From Geek to Star #19 - "Writing specs is so yesterday“...?

If you missed the previous episodes, you can access them online here.

Dear reader, next Saturday will be my birthday 🙂, so I will share in my newsletter next week a gift with you for that occasion : the framework I have been designing to better succeed in an engineering career in this AI-age. If you've been enjoying reading this newsletter so far, do not hesitate to share about it to other engineers / leaders in your circle! #sharingiscaring!

🗓️ This Week – Episode 19: Is writing specifications the “new Black” in this AI age?

“The new scarce skill is writing specs that fully capture intent and values. Whoever masters becomes the most valuable programmer”. Now, that is a claim that struck me while watching a video this week by Sean Grove, technical staff at OpenAI, in a recent talk on “The New Code”. 

In my 27 years of professional experience, including a few years as a functional analyst, I've always thought that knowledge management was essential but I've rarely seen it executed well. And over years, I've often seen leaders and teams often dismiss written documentation:

• “No one reads the documentation anyway”

• “The truth is in the code, not in a pile of outdated documents”

• “We are agile, we don't do specs” (a wrong interpretation of agile by the way) 

So I was very intrigued by this talk about the revival and importance of specifications. Much like the Jedi saber which disappeared for some time until young Luke Skywalker discovered the Force through Obi-Wan?

Here is a summary and my thoughts, do build your own thoughts on these as well!

🗣️The Real Value: Communication Over Code

Grove challenges the common perception that code is an engineer's most valuable artifact. He argues that code represents only 10-20% of the value an engineer brings. The vast majority, 80-90%, lies in structured communication. This includes understanding user challenges, distilling stories, ideating solutions, planning, sharing those plans, translating them into code, and crucially, testing against the original goals.

This "structured communication", knowing what to build, how to build it, why it's being built, and verifying if it achieved its intended purpose, is the true bottleneck in development. As AI models become more advanced, the ability to communicate effectively and capture it would become the most valuable programming skill - however, much like with the Agile manifesto, it does not mean that other skills such as technical design, coding skills are not needed. 

📚Specifications: The New Source Code?

Consider "vibe coding," where models generate code based on a described intent. While it feels productive, Grove points out a critical flaw: the prompts (capturing intent) are often discarded, while the generated code is kept. If you think about it, it is like version-controlling a compiled binary while shredding the source code.

Written specifications are presented as the truly valuable artifact. They capture intent and values, align humans on shared goals, and serve as the foundation for discussion, debate, and synchronization. Code, in this view, is merely a "lossy projection" of a specification; it doesn't fully embody all intentions and values. And it is true, if you think about it, a robust specification, much like source code for a compiler, can generate various outputs thanks to GenAI now: be it TypeScript, Rust, documentation, tutorials, or even blog posts and videos, and for different targets. A kind of “write once, generate code everywhere” if you like. 

OpenAI's Model Spec: A Living Example

The talk shows how OpenAI has embraced this philosophy with its "Model Spec", a living, open-source document that clearly expresses the intentions and values for its models. This spec is a collection of markdown files, making it human-readable, versioned, and accessible. Crucially, its natural language format allows diverse non-technical stakeholders (product, legal, safety, policy, research) to contribute and align on the same "source code".

👩🏻‍💻Building automatically systems through specifications

Specifications aren't just for humans anymore today: they can automatically align AI models.  These specifications can embed various requirements, from code style to safety. Grove emphasizes that even in markdown, specifications are analogous to code: they compose, are executable, testable, have interfaces, and can be shipped as modules. They offer a toolchain focused on intentions rather than syntax. For example, The US Constitution is cited as a powerful example of a national model specification, complete with written policy, versioned amendments, judicial review (grading), and precedents acting as unit tests.

This leads to a profound conclusion: programmers, product managers, and even lawmakers are all "spec authors". Those who will know how to structure, document, write this content and then leverage on AI will be the people who master the “Why” and “What", delegating the “How” to genAI - with still technical human expertise in the loop as “peer” review. 

Your Next Step: Become a Spec Author?

Grove's call to action is clear: For your next AI feature, start with a clear specification, both functional and technical. Define what you expect to happen and what success looks like.

Disclaimer: again, I don't think it means other technical skills are not needed. Even with well structured and clear specs, you still need to have skills to check if the code generated is maintainable, if it seems optimized enough, etc…

What I found also very interesting through this talk is that being good at this “hard” skill also involves many others we went through in the past newsletters: soft skills such as communication (here through clear specifications written), industry knowledge to be able to write relevant specs, network nurturing to really capture the intent of your stakeholders, experience to inject the expertise into the specs. 

It is much more than being just good at prompt engineering, it is about the ability to structure, design and document (and keep updated) a whole system you want to build and maintain, which will serve as the foundations of all things then generated by GenAI: website, mobile app, videos, podcast, dashboards… Knowledge Management becomes critical not just for the sake of keeping the history but as the source of truth and “source code” of all the binaries generated. 

🙏 I’d Love to Hear From You

Do you think that Knowledge Management and written documentation is going to become the pillar of good software engineering? 

Reply to this email, I read every note.

And don’t forget: follow me on LinkedIn for more reflections and “behind-the-scenes” thinking between newsletters. Don't hesitate to engage discussions there in the comments to also start showing and sharing your thoughts publicly. 

✨ May the Shift be with you!

From Geek to Star by Khang | The Way Forward