Whether you’re writing technical specs, functional docs, user stories, or code, providing clarity and understandability should be your top priority. Trust me, your future self (and anyone who comes after you) will thank you!

Assume you won’t be around to explain your thought process. Write for the new hire who just joined. Write for the junior dev still learning the ropes. Write for the executive leader who won’t sit through every team meeting but still needs to grasp the big picture.

If you're not sure where to start, I have some tips and ticks that may be helpful next time you are the keyboard staring at a blank screen.

Unnecessarily Clever Code

I recently read a post by Josh Comeau ( a well known frontend guru who I admire) called "Clever Code." This post really hit home for me and I couldn't help but reflect on my own experience navigating complex codebases.

I remembered a time when I was asked to contribute to a codebase that was massive—loaded with dependencies and abstractions. Ramp-up was painfully slow because documentation was practically nonexistent. On top of that, the logic was buried under layers of indirection, and the variable names where often cryptic and hard to decipher. While trying to contribute meaningful work, I found I needed the constant help of teammates to explain the context but they had their own deliverables to worry about!

As Josh pointed out in his article, "When it comes to day-to-day production code, here's the barometer I like to use: will a junior developer, someone at the very start of their career, struggle to understand this code?. . .good code, is simple code."

I know that this is much, much easier when you get to control the initial structure of a codebase. And, it gets way more complex when you are thrown into legacy systems where the original authors are no longer are around. That said, writing things in such a way to make them understandable for everyone is a skill and one that can easily be learned and practiced.

Well Documented Code

If at all possible, seek to provide as much documentation about your codebase as possible.

• Good README files I've often found to be treasure troves of information.

• Follow consistent formatting and style guides. Make your variable names intuitive and follow a standard convention. Readable code is predictable code. Stick to your team's conventions.

• Don't be afraid of comments in code (it can be supremely helpful).

• Make use of comments in code reviews and in Jira tickets. The sort of historical information they provide for those that come after you (or when you, yourself, come back to a feature after a couple months) is invaluable.

• Use code reviews to improve not only the functionality but the clarity of code being written.

• Write comments for why , not what – Assume the code is self-explanatory. Use comments to explain decisions, edge cases, or trade-offs.

• Break down complex logic – If a function needs a paragraph of comments to explain itself, it's probably doing too much. Refactor it.

• Use clear error messages – "Error 401" is useless. "Unauthorized: Your API key is missing" is better.

Most importantly do your best to establish a review cadence of the documentation you do have. Codebases change and so should the documentation that supports it. This is easier said than done, I know, but if you establish a pattern and it becomes part of your team's work it is a life-saver!

Write For The New Hire

Early in my career, a Program Management Leader gave me a piece of advice that has always stuck with me: "Write for 'Joe-Schmoe' on the street—the person who knows nothing about our team or our project."

I started doing this with the functional specifications I wrote. If we used acronyms, they were defined upfront. If there were unusual terms, they were explained at the beginning. Writing this way didn’t just help the team—it made onboarding smoother and specs clearer for anyone who came later.

Many times, in the corporate world, we get so used to our own jargon that we forget that what is obvious to us, is not always obvious to people from other departments, teams, or companies who will later read our documentation and rely on it for context and information.

Well Written Specs

• Use headings and bullet points liberally – Walls of text are intimidating. Break it up for easy scanning.

• Use examples and analogies – Especially for technical topics, real-world comparisons make concepts stick.

• Avoid jargon when possible – Write for the broadest audience that needs to understand your writing. If using jargon define it upfront so that your readers don't have to guess at what it means.

• Define acronyms terms early – Never assume people know what things like "TPM" or "OKRs" mean. Spell it out the first time it is used in any document.

• Structure information in logical order – Lead with the "what" and "why" before diving into the details.

• Read what you write out loud to yourself. You'd be surprised how reading out loud really improves the clarity of your writing.

• Proof-read what you've written a couple days later. The time away gives you a fresh perspective.

• Review your documentation on an iterative, ongoing basis and update as needed.

• Have a friend (or Gen AI) review what you've written for clarity, flow and readability and then provide feedback for areas of improvement.

Using AI

I've been making great use of Generative AI tools such as ChatGPT to help with my writing. Like many things with GenAI tools the idea is to provide assistance. Avoid simply copying and pasting. Everyone can tell (wink, wink). Instead I like to use the following tips for making good use of GenAI tools:

• Write a draft or outline of your subject and let GenAI give you further inspiration or pointers to assist with any writer's block. AI provides some great jumping-off points.

• Act like an editor: have AI clean up your paragraphs and document but don't leave it at that. Review it yourself. Act as if AI is your assistant author and you are ultimately the lead editor of your content.

• AI can provide better flow, readability and grammar but don't leave out your own voice! Make sure when you review your writing it is a real reflection of who you are. It shows!

• AI is also great for crafting relevant and engaging images and diagrams that support your content. I used StockCake for an AI generated title image for this article. The image for this section was generated using Sora by OpenAI.

Writing Is Communicating

At the heart of it, writing (code, specs, or business docs) is about communication. Write like someone’s future success depends on it, because in many cases, it does. Write documentation that helps the next person (or your future self) get up to speed without frustration. Write code that’s readable, maintainable, and doesn’t require a doctorate to decipher.

Good writing is simple, direct, and effective. It doesn’t rely on jargon, unnecessary complexity, or clever tricks. It prioritizes the reader, removes ambiguity, and makes knowledge accessible.

So, before you hit “submit,” ask yourself: Will this make sense to someone new? Will this save time and reduce confusion? Will this help, rather than hinder? If not—edit, refine, and simplify.