How to Write Clear Project Notes for Developers

After more than a decade and over 1,000 web development projects, we’ve seen just about every communication method out there—Figma comments, Slack threads, scattered email chains, mile-long Google Docs, and everything in between. Some work better than others. Most leave room for confusion.

The project notes template we use at Hey Reliable didn’t come from a textbook or an industry standard. It came from real experience—watching where projects tend to break down, seeing what consistently works, and formalizing a system that bridges the gap between design intent and development execution.

Here’s the thing: most clients today don’t provide project notes at all. And that’s fine—we never require them. But when clients do take the time to write clear notes? Those projects go infinitely smoother. There’s less back-and-forth, fewer assumptions, and a much clearer path from design to deployment.

So we’re sharing our internal template here—not because you have to use it, but because we know it works. Use it as-is, adapt it to fit your workflow, or just borrow the parts that make sense for your team.

Why Design Files Aren’t Enough

Figma is incredible. So are Sketch, Adobe XD, and every other design tool out there. They show layout, spacing, typography, and visual hierarchy beautifully.

But here’s what they don’t show:

• CMS logic – Which sections are global? Which are page-specific? What’s editable?
• Conditional behavior – What happens when there’s no featured image? When a headline is three lines instead of one?
• Interactive states – How should that dropdown behave? What triggers the modal?
• Edge cases – What’s the max character count for a headline? What happens if there are 47 blog posts instead of 3?
• Mobile-specific decisions – Does the desktop sticky nav translate exactly to mobile, or does it behave differently?

Design files show you what something should look like. Project notes explain how it should work.

Without that second layer of instruction, developers are left to guess. And when developers guess, you get revisions, rework, and delays.

What Makes This Template Different

Most project documentation falls into one of two extremes: too vague or too overwhelming.

Vague notes create confusion. (“Make this section feel premium.” Okay, but… how?)

Overly detailed specs become hard to maintain and easy to misinterpret, especially when buried across multiple tools.

This template finds the middle ground. It’s structured to be:

• Clear – One instruction per line, paired with a visual reference
• Organized – Global elements first, then page-by-page
• Actionable – Focused on behavior, logic, and “what happens when” scenarios
• Scannable – Developers can quickly find what they need without digging

It separates design explanation (why it looks this way) from build instruction (how it should function). That distinction matters.

The Template: How to Use It

Start With Project Context

Before diving into specific instructions, give your development team the big picture:

[Project Name]

[Project Type / Technical Spec]
Examples: WordPress with Advanced Custom Fields, Custom WordPress Theme, Webflow build, React app, etc.

[Link to Designs]
Figma, Sketch, Adobe XD—whatever you’re using. Include a separate prototype link if you have one.

[Link to Current Site (if applicable)]
If this is a redesign or rebuild, link to the live site.

[Link to Other Assets]
Fonts (TTF/OTF and WOFF/WOFF2 files, or a Google Fonts link), brand guidelines, any plugins or tools we’ll need access to, API documentation, etc.

[Context]
A brief description of the business or organization and the project. You don’t need to write marketing copy here—just enough context so the team understands who the client is, what they do, and who the audience is.

This upfront context prevents a lot of clarifying questions later.

Organize: Global First, Then Page by Page

Start with a Global section for anything that applies across the entire site or multiple pages:

• Header behavior (sticky? resizable? hidden on scroll?)
• Footer elements
• Navigation logic
• Shared components (CTAs, forms, popups)
• Global animations
• CMS-wide rules

Then break down notes page by page, view by view, or by template/component—depending on how your project is structured.

Format: Screenshot + Instruction

For each instruction, use this format:

[Screenshot link] – [Brief instruction]

We use Teampaper Snap for screenshots because it’s fast and generates shareable links, but you can use whatever works for you—CloudApp, Droplr, Loom for videos, etc.

Here are some real examples from past projects:

https://tppr.me/mtZ8M – Make the header sticky and resizable; it should appear only when the user scrolls up, not when scrolling down.

https://tppr.me/nKZqH – Clicking the “Plan a Trip” button in the header should open the “Plan a Trip” form, starting at step 1 and progressing through steps 1–6.

https://tppr.me/bEKMs – The hero area should support either a video background or an image slider, selectable from the CMS.

Notice the pattern? Each instruction:

• Points to a specific visual reference
• Describes exactly what should happen
• Includes any conditional logic or CMS flexibility needed

Be Specific, Not Vague

Avoid phrases like:

• “Make this feel elevated”
• “Invoke a sense of movement”
• “Convey a professional mood”

Those are design decisions that should already be baked into your visuals. In project notes, focus on the functional and technical details that aren’t obvious from the design file.

Instead, write things like:

• “This section should fade in when it enters the viewport, with a 0.3s delay between each card.”
• “The mobile menu should slide in from the right and overlay the page content.”
• “If no featured image is set, default to the placeholder image located in [folder/link].”

For Interactive or Animated Elements, Go Step by Step

If something is interactive, dynamic, or animated, describe the full user flow:

• What triggers it?
• What happens next?
• Are there multiple states?
• What’s the default state?
• What happens on edge cases?

Even better: include a live reference link if you’ve seen the interaction done well elsewhere. Tools like Loom are great for recording quick video walkthroughs when text alone won’t cut it.

Just remember: complex animations are often collaborative and iterative. They’re rarely 100% perfect on the first pass, and that’s okay.

Why This Matters

Clear project notes don’t just help developers—they help you.

When instructions are specific and well-organized from the start, you get:

• Fewer rounds of revisions
• Faster development timelines
• Less back-and-forth clarification
• Fewer missed details
• A final product that matches your vision

The projects that go smoothest aren’t necessarily the simplest ones. They’re the ones with the clearest direction.

Use This However It Helps

You don’t need to follow this template exactly. You don’t even need to use a template at all. But if you’ve ever felt frustrated by miscommunication, endless revision rounds, or a final product that didn’t quite match what you had in mind—this system can help.

We use it internally because we know it works. And we’re sharing it because we genuinely love when clients take the time to document their projects clearly. It makes the entire process smoother for everyone involved.

Feel free to adapt it, remix it, or use it as a starting point for your own process. Whatever makes your projects run better.

Full Template

Access the full project notes template in Google Docs — duplicate it and customize it for your project.

Need Help With Your Next Project?

Whether you’re working on a single landing page or a complex web application, Hey Reliable handles the full technical build—from front-end development and CMS integration to performance optimization, accessibility, privacy compliance, and beyond.

We partner with agencies, designers, marketing teams, software developers, and businesses across industries to deliver clean, scalable code that works exactly as intended.

What we do:

• Front-end development (HTML, CSS, JavaScript, React, Vue, Next.js)
• CMS development (WordPress, Craft CMS, Webflow, headless options)
• Back-end development (PHP, Laravel, REST APIs)
• UI/UX design and design systems
• E-commerce builds (WooCommerce, Stripe, custom checkout flows)
• Performance optimization and Core Web Vitals
• Technical SEO and accessibility (WCAG compliance)
• Privacy compliance (GDPR, CCPA, Google Consent Mode)
• Third-party integrations (CRMs, analytics, marketing tools)
• White-label development for agencies

Get a free proposal and see how we work—no obligation, delivered in one business day or less.

Mary Marnell

Managing Partner · LinkedIn

Mary Marnell is Managing Partner at Hey Reliable, a front-end and WordPress development agency known for delivering clean, reliable code for agencies, marketing teams, and growing businesses. She joined the company in 2017, became partner in ... read more