Documentation can be a sticky subject among designers. Some of us will tell you we should all be doing more of it while others strongly question its value, both justifiably. What usually dominates the conversation, though, is either handoff documentation like style guides and redlines, or discovery documentation capturing what was tried, tested, learned from, and ultimately decided either upon or against. While spelling out design patterns and snapshotting iterative discovery for future reference are worthwhile pursuits, they’re hardly the only things worth putting in writing.

Most designers who work in software have at some point encountered the README file of a code repository. While these vary in scope, style, and detail, including one is generally considered best practice especially for projects with many concurrent contributors or projects that change hands with some regularity. In this post, I’ll share how design teams can adapt and benefit from this practice, but first let’s zoom out and look at why it’s a good idea in the first place.

Why write a design README?

Every designer has a somewhat unique and idiosyncratic way of working. Our software setups vary, we structure our files differently, some of us are okay with layer names like Rectangle 17 copy 4, others not so much. While discrepancies in the way we work don’t matter so much when we’re lone wolves, they quickly become consequential when we’re working in a team environment or when personnel shuffles and someone has to pick up another’s work. In these inevitable scenarios, we soon feel the pain of either having to sort out the logic of someone else’s way of working, or having to waste time modifying their work to align to our existing muscle memory, or having to clean up work that was put together poorly in the first place but needs to made reusable.

While a README isn’t a perfect solution for any of these cases, it’s a step in the right direction. A good README levels the playing field between people with close proximity to the project and people who are digging in for the first time. It makes explicit conventions and expectations that might otherwise be left to individual pattern recognition, and helps the uninitiated get their bearings when diving into a new file. Most of all, it helps teams operate from a common set of rules, patterns, and assumptions, and minimize complicating divergences over time.

Investing the time required to write a great README up front saves design teams with any real growth prospects hours if not days to weeks of remedial effort and communication as the team scales and its lineup changes.

An added benefit of a well-written README is its use as a focus tool. This applies to small, stable teams as much as teams with higher growth and/or turnover. As projects or product cycles progress, it’s easy to lose the forest for the trees and become so fixated on one facet of the work that you forget what you’re doing and why and how you’re doing it. While much of a README’s contents are procedural, good ones also capture the 10,000 foot view of the problem and opportunity. Referring to it periodically can be a sort of “pause for the cause” that renews beginner’s mind and reorients long-serving contributors to the big picture and basics of operation.

Our Design README Framework

So what does a design-oriented README include? That’s likely different for every team and project, but below is a framework we’ve had success with at Livefront. We provide an example at the end of this article.

Thesis

Start with a one-sentence summation of the product or feature and the human need it serves. Keep it punchy but detailed enough for someone who’s new to the idea to grasp the concept right away. This might be a key use case or job-to-be-done, or just a good old fashioned elevator pitch. What it’s not is a slogan or tagline; it should be concrete and detailed enough to get the idea across immediately. Some inspiration can be found in the loglines screenwriters have long used to pitch their scripts, like this one for James Cameron’s Titanic: “A young man and woman from different social classes fall in love aboard an ill-fated voyage at sea.” In just a few words, you get an intuitive sense of who it’s for and what it’s about. A good product or feature thesis does the same thing: it tells you something meaningful about who wants the thing you’re making and why.

To apply this concept, let’s take the example of Lyft. A thesis for its flagship rider app might be: “Lyft lets you find a friendly, affordable ride whenever you need one, at the tap of a button.” (Indeed, that’s cribbed almost word for word from its App Store page, which can be a great place to look for thesis material if you’re working on a mobile app.) That’s pretty good, but Lyft has a big design team and their work is probably spread out across a number of discrete features and focus areas. Let’s say a swarm team dedicated to Lyft’s advance scheduling features wrote its own README. Theirs might read something like: “For the times when you need to plan ahead, Lyft scheduling let you easily book a friendly, affordable ride in advance so you can get where you need to go, effortlessly.” Same basic idea, just zoomed in a little bit. You want to distill the core value of whatever you’re working on down to its essence, with just enough specificity to paint a crisp mental picture.

🔥 Tip: for teams organized around Jobs-to-be-Done, your thesis is likely your right there in your job statement: “When [x], [product/feature] helps you [y] so you can [z].”

Setup

Next, explain how to get set up with everything a new member of the team would need in order to be effective right away. Think of this like a recipe: a simple set of easy to follow, step-by-step instructions for configuring the requisite design environment. At a minimum, it includes:

• Software: what desktop applications does the team use for 2D design, 3D design, prototyping, and/or developer handoff, and what version(s)?
• Plugins: what (if any) plugins or extensions are required?
• Libraries: what symbol or component libraries need to be linked, and where does the single source of truth for each live? Are there corresponding design system guidelines documented somewhere?
• Fonts: what typefaces or icon fonts need to be installed, and where are those assets found?
• Master File: what (if any) master file or template should be branched as a starting point for iteration?

Additionally, it may make sense to include account setup or linking instructions for any cloud services you’re using for key workflows like file storage, version control, or even UI design (👋 Figma). If you’re designing with live JSON data, link to or include instructions for hitting relevant API endpoints as well.

🔥 Tip: after you finish writing the setup section of the README, have a colleague try getting set up from scratch using only what’s written. If anything is revealed to be assumed, implicit, or unclear, update the instructions accordingly. Then, as new people join the team, invite them to suggest continuous revisions based on their experience actually using it in context of onboarding.

Naming & Versioning

For teams managing files and versions manually, use this documentation to capture any shared file naming conventions in writing. To effectively mitigate file chaos, naming and versioning guidelines should include a few things:

• The basic structure of a correctly named file (ex. “[YYYYMMDD] — [Description] [Version].xyz”)
• The version model used to track ongoing work (ex. “3.0”, “Rev 4a”, “July 2018”). This may align to the release model used by the broader product organization, or may be totally removed and unique to the design team.
• The branching conditions, or when to break off a new a file and increment the version. This might be determined based on the scope of changes, the release of a new build, or the passage of a certain length of time.

🔥 Tip: for teams using an automated file management and version control system like Abstract, clarify how to launch, and commit files correctly so version information is captured, as well as how, when, and why to branch files.

Workflow

Lay out the high-level workflow and specify which tools are used for what. Design teams tend to work in a pretty consistent sequence or cycle, with different tools corresponding to each stage:

• Ideation: the initial research and concepting phase. Tools used at this stage might include whiteboards and Camera.app, Invision Freehand, or Dropbox Paper.
• Experience & Visual Design: the drawing and compositing at various levels of fidelity that constitutes the bulk of design production work. For most teams, this is Sketch, Figma, or Framer X.
• Prototyping: the interactive rendering of design comps for testing, demonstration, and handoff purposes. This is probably some combination of tools ranging from simpler options like InVision to more robust choices like Principle, Framer, or Origami.
• Collaboration: the feedback, communication, and iteration loop. InVision, Sketch Cloud, and Zeplin are popular tools for this piece.
• Handoff: the stage at which design artifacts are turned over to the dev team for implementation. Zeplin and InVision lead the pack here but other tools like Avocode and Gallery are out there too.

Great teams are always experimenting with new tools so this list doesn't need to be exhaustive, but it should be a complete representation of the “go to” tools used on a day-to-day basis for core tasks and workflows.

🔥 Tip: be clear about how each tool should and should not be used, particularly where there are overlaps in functionality. For instance, if using InVision for collaboration and Zeplin for handoff, clarify that Zeplin’s commenting feature shouldn’t be used to capture design feedback and only final, production-ready UI comps should be committed to Zeplin.

Style

Establish stylistic conventions for your working files similar to the way a developer style guide might specify approaches to things like indentation and object naming. Questions to answer include:

• Structure: how are pages named, numbered, and utilized? How, if at all, are different features broken up into multiple working files? What’s the maximum appropriate scope of a single file?
• Artboard Naming: how are individual artboards named and numbered, and what are the conventions for denoting state and parent-child relationships?
• Layer Hygiene: how are individual layers and symbols named, ordered, and/or grouped? How should symbols be nested? Are asset export paths defined via the layer name property?
• Flow Mapping: how are actions and screen relationships visualized?
• Devices: what is the default screen size being designed for, and what if any additional resolutions need to be validated?
• Spacing: how should layers be spaced and snapped? Is there a standard grid, and if so where are those guidelines found?
• Constraints: what are the expectations insofar as constraints and resizability are concerned? Is this enforced at the symbol level, or globally across all artboards?
• Export Settings: how should the export settings for sliced layers and artboards be configured by default?

🔥 Tip: depending on the size of the team and the number of concurrent streams of work, some or all of this information might exist as a separate, linked resource for shared use across multiple projects and/or teams.

Deciders

Another useful thing to put in writing is who has pertinent and necessary decision rights. These might be people on the team like a product manager who decides when a new feature is done, people above or parallel to the team like a design director who reviews and greenlights all outgoing work, or people outside the organization like a client or partner with final say. There shouldn’t be many of these people, but the list should be complete enough for any new member to instantly get a sense of who’s driving the bus, whose input and approval needs to be sought when, and who can dislodge impediments when they turn up.

Experts

In addition to decision makers, it can be helpful to identify people within the organization who either possess an unusual depth of knowledge about the problem space or provide a direct line of communication to a different, related team or practice area. These may be designers who’ve worked on the same or a similar feature in the past, sales or service partners who are close to the customer, operations partners with relevant domain expertise, or someone who previously worked on a competitive product. This list shouldn’t be long either, just the few go-to people who are uniquely equipped to shed valuable insights or translate a foreign working language.

🔥 Tip: if you were holding a GV-style design sprint next week, these are the people you’d be inviting to the “Ask the Experts” portion of Day 1.

Outcomes

Lastly, it’s a good idea to spell out the outcomes against which the team’s performance will be appraised. These can be dates and milestones, key metrics, OKRs, or any other outcome the team is accountable to deliver. They’re often dynamic and may live in their own place like a Google Sheet or Confluence space, in which case linking to them is all that’s needed. The idea is simply to provide up-front context for how success is measured and how decisions are made. Think of this as a bookend to the thesis statement; the thesis captures the problem to be solved and the outcomes are barometers for measuring the efficacy of the solution.

How to get the most from a README

Documentation is only effective to the extent it’s understood and embraced within the organization. There are a few things you can do to increase the odds of successful adoption and adherence by your team:

• Keep it tight: you’re writing a README, not a novel. Be detailed about the things that matter, but also clear and concise. Again, the idea is that someone who is new to your project (or someone who just needs a casual refresher) can get their bearings quickly. The longer and more densely worded your document is, the less likely your colleagues are to read, internalize, and return to it.
• Links are your friend: if there are certain sections that are particularly long and/or heavily reused — think style guides, versioning frameworks, codes of conduct — link to a canonical instance. This keeps the document information-dense but lightweight, and makes a handy reference for anyone trying to track those links down in the future.
• Don’t repeat yourself: a project README should have a single source of truth and shouldn’t be duplicated. Developers store theirs in the root directory of the project repository. Yours might live in a Dropbox folder, or in a Notion workspace, or as a Google Doc. Whatever you do, don’t embed them directly in your working files, as this inevitably leads to duplication and discrepancies.
• Stay up to date: software projects aren’t static and neither should their documentation be. When the focus of the product or feature you’re working on changes, so should the written thesis. When the goalposts move, so should the stated outcomes. When your team updates to a new version of Sketch, the setup instructions should reflect that. Your README is a living thing, just like the team, the tools, the work, and the market.

Writing and maintaining a project README may seem like a headache, but it needn’t take a ton of time and the benefits compound in the long term. To give you a running start, we’ve provided the example below to copy as a reference. Feel free to use, remix, and share it. As you learn what works well for your team and what doesn’t, we’d love to hear about those discoveries. Leave a response on Medium or tweet us (we’re @Livefront)… we’re anxious to hear how it goes!

Did you enjoy this article? If so, let us know by sharing it and pressing and holding the “clap” button below! Want more like this? Follow us on Medium and Twitter at @Livefront. Also, we’re hiring!