Before you code, write.

You’ve spent weeks developing a new feature for your app. You’ve obsessed over every interface detail and finished off every rough edge with the lightest grade of sandpaper. You’ve squashed every bug. You’ve tested and re-tested. Everything is looking good and ready for takeoff. Only thing left to do now is write up a knowledge base article explaining how the new feature works, plus an accompanying blog post and email newsletter to tout its greatness. It’s all downhill from here…right?

If you’re a product designer or developer like me, you’ve probably found yourself waiting until the very end of your development cycle to document how an application feature works.

If there’s one thing I’ve learned from multiple years of concepting, prototyping, testing, and deploying final builds of application features and APIs, it’s this.

Before you code, write.

I speak from experience. Multiple times I’ve sat down to write a knowledge base article while basking in the warm glow of a post-development battle. I’d start with an introduction summarizing a feature’s usefulness, followed by a real-world example, followed by a 1–2–3 walkthrough. Sometimes the writing would be easy and fluid. Other times I’d get halfway through, my progress would slow, and I’d realize the unfortunate reality of my situation.

I can’t clearly explain how this works. To myself.


Concepting application features in the abstract is typically a process involving PSDs, InVision prototypes, vanilla HTML markup, flowcharts, wireframes, or some combination of the above. All are incredibly useful when capturing how a feature might look and feel. But the real test comes when your target audience attempts to use it.

Unfortunately, user feedback on the relative success or failure of your interface design (graphical or API) isn’t typically discovered until after the fact through user experience studies or user feedback. Sometimes this works in your favor. Other times, a flaw in your approach is pointed out and you’re stuck perpetually agreeing that a feature you implemented is less than ideal.

So what’s the alternative? How can real-world feedback and experience be folded into the initial design/development phase when you don’t have anything to test?

Here’s an idea. Instead of only showing how a feature or API function works through a visual prototype or code sample, explain how it works using words.

For example, imagine you’re sitting with someone you know — a friend, relative, colleague — and they’ve never used your product. A blank slate. How would you go about explaining the usefulness of what you created? Which details would you include? Or perhaps more importantly, which details would you leave out?

This discovery process is similar to writing taglines, advertising copy or elevator pitches. Your goal is to succinctly communicate with your audience a central message, call to action or idea in the most efficient manner possible. The relative success or failure or your communication isn’t simply a measure of verbosity, but rather how compact and clear you can compress your message into a form the end user can understand.

User interfaces — graphical or otherwise — adhere to the same principles. The best interfaces are the ones that look and feel obvious, no manual required. Extraneous ornament and unnecessary detail have been removed to focus the user’s attention on the task at hand. The interface’s usefulness and utility is a direct expression of your ability to communicate its functionality using words.

Challenge yourself to write a single sentence that captures the entirety of a feature’s utility. If the feature is a multi-step process, write every step from start to finish. If you find yourself writing detours suggesting users move forward or backward in the instructions, revisit your design. If you find yourself reaching step eight, step nine, revisit your design. Consider how the interface could be refined to support a simplified flow. Challenge yourself to create an experience that effectively and expediently guides a user to the finish line in the fewest number of steps.

Elegant, efficient, beautiful software doesn’t magically appear. It’s the direct result of an editorial process that emphasizes user experience and clear communication. Your users will thank you for it.

Published in #SWLH (Startups, Wanderlust, and Life Hacking)

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.