Introduction

This wiki page contains notes about the design of Jupyter/IPython related apps and websites. In this context "design" refers to the parts of our software and websites that are visible to and used by our end users, rather than the internal software design. This user focused design includes both visual and interaction design.

Software design principles

When we write code for IPython and Jupyter, we constantly refer to different software design principles. While we haven't written them down (maybe we should), we have developed these principles over many years of writing software ourselves and studying how others write software. Here are some examples of software design principles we follow:

• The ideas put forward in Python's this module, such as "readability counts" and "errors should never pass silently."
• Don't repeat yourself. If a particular code path appears more than once, refactor it into a function/class that can be reused.
• Functions and methods should be relatively short and do one thing. When they get to more than a few dozen lines, they should be broken into logic pieces.
• Follow PEP 8 for code styling.
• Keep Pull Requests focused on one thing and as small as possible.
• Group code into logical and conceptual units using modules, namespaces and packages.
• Don't break core abstractions.

These software design principles are important for a number of reasons:

• They enable us to review each other's code in a specific, productive and helpful way. We can say "this function is doing too many thing and should be refactored into 3 parts" rather than "I don't like this function."
• They give us concrete language and concepts to use in discussing the properties of our software.
• They enable us to not have to think about many things. How many naming and code style choices we would have to make without PEP 8?

The goal of this wiki page is to create such principles for our visual and interaction design work.

Visual and interaction design principles

General design principles

• Design for a wide range of devices and aspect ratios.
• Maximize information density (Tufte).
• Use prototypical design patterns when they exist.
• Prefer simple to complex.
• Create a clear visual hierarchy.
• Embrace white space.

Jupyter/IPython specific design principles

• User content is primary, anything else must be subtle.
• Minimize visual complexity and cognitive load. Our users are solving difficult technical problems and need to focus on that.
• Vertical space is precious, don't use it up unless there is a good reason.
• Our design must not be strongly opinionated or trendy, it has to work across a wide range of contexts, from theoretical physics to the White House.

References

We are trying to learn as much about design as possible. The following are some books and resoures we have found to be useful in this process. If you are interested in helping us with the design of Jupyter/IPython, we encourage you to read these books. We also encourage you to add your own favorite resources about design here.

• Don't Make Me Think, Revisited by Steve Krug.
• Design for Hackers by David Kadavy.
• The role of visual complexity and prototypicality regarding first impression of websites: Working towards understanding aesthetic judgments by Google Research.
• Lean UX by Jeff Gothelf and Josh Seiden (O'Reilly)

Notes from Krug's Don't Make Me Think

• Don't make the me think. A web site should be self-evident, obvious and self-explanatory.
• We don't read web pages, we scan them.
• We are in a hurry and don't make optimal choices, we pick the first reasonable option.
• We don't figure out how things really work, we muddle through.
• Take advantage of conventions: where things are located on a page, how things work, how things look.
• Create effective visual hierarchies:
  • The more important something is, the more prominent it is.
  • Things that are related logically are related visually.
  • Things are "nested" visually to show what's part of what.
• Break pages into clearly defined areas.
• Make it obvious what's clickable.
• Keep visual noise down. Get rid of anything that is not making a real contribution.
• Format text to support scanning:
  • Use plenty of headings.
  • Don't fill justify body text.
  • Keep paragraphs short.
  • Use bulleted lists.
  • Highlight key terms.
• It doesn't matter how many times, as long as each click is a mindless, unambiguous choice.
• Omit words. Get rid of half the words on each page, then get rid of half of what's left.
• Happy talk must die. This is narrative text that welcomes us to a page telling us what we are about to see.
• Instructions must die. No one ever reads instructions. Make it a goal to make things so obvious that instructions are not needed. If they are needed, they should be as minimal as possible and not require thinking.
• People won't use your web site if they can't find their way around it. Web sites lack spatial information for navigation that physical spaces and objects have. Pages must provide "clear, simple and consistent" navigation.
• Navigation tells: what's here, how to use the site and gives us confidence in the people who built it.
• Offer persistent navigation on every page that allows users to navigate the entire site and see where they currently are.
• Every page should contain tha "site id" or name of the site.
• Every page should have a page name telling what page this is. The name needs to be in the right place and needs to be prominent. The name should match exactly what I clicked to get to that page.
• Pick a random page on your website and ask the following questions:
  • What site is this?
  • What page am I on?
  • What are the major sections of the site?
  • What are my options at this level?
  • Where am I in the global scheme of things?
  • How can I search?
• There are a million things that clamor to be on the homepage. But there is one things that can't get lost in the shuffle: the big picture. What is this? What can I do here? What do they have here? What should be here an not somewhere else?
• The home page has to spell out the big picture clearly.
  • Include a short tagline nearby the logo+site name.
  • Include a welcome blurb - a short description of the site. But don't put a mission statement here.
  • Use the "Learn More" pattern to direct users to the next steps.
• The home page must also answer the "where do I start" question.
• Most arguments about usability are a waste of time. Do usability testing instead.
• Things that diminish a goodwill:
  • Hiding information that they want.
  • Punishing them for not doing things your way.
  • Asking them for information you don't really need.
  • Shucking and jiving them.
  • Putting sizzle and marketing in their way.
  • An amateurish looking site.
• Things that increase goodwill:
  • Know the main things that people want to do on your site and make them obvious and easy.
  • Tell users what they want to know.
  • Save users steps wherever you can.
  • Put effort into it.
  • Know what questions I'm likely to have, and answer them.
  • Provide me with creature comforts.
  • Make it easy to recover from errors.
  • When in doubt, apologize.