Continued from day 1.

How Documentation Works and How to Make it Work for Your Project (by @evildmp)

  • Video
  • Blog
  • Better docs will make your project more successful
  • If your documentation sucks, people will refuse to use your software
  • The secret: there are four different kinds of documentation, and all are necessary:
    • Tutorials: hand-hold reader through a series of steps. Main goal: learning. Analogy: teaching a child to cook.
    • Howto guides: show the reader how to solve a common problem. Analogy: cooking recipe.
    • References: technical description. Analogy: an encyclopedia article about a cooking ingredient.
    • Discussions: explanations that clarify and illuminate a particular topic. Analogy: a book of historical/sociological discussions about cooking.
  • Modes of writing are different for each kind
  • They must be separate to each other

Readability Counts (by @treyhunner)

OK, I didn’t actually go to this one because it was at the same time as the documentation talk, but it’s worth reviewing anyway.

Awesome Command-line Tools (by @amjithr)

… didn’t go to this one either, but it’s worth reviewing. Comes with live coding :)

  • Video
  • pgcli, mycli
  • Bringing discoverability to command line applications
  • bpython
  • “Configurability is the root of all evil”
  • Only use configuration options for things you can’t automatically figure out for the user
  • Checklist for implementing an interactive shell
    • Persistent history
    • History search
    • Emacs keybindiings
    • Paged output
    • Auto-completion
    • Minimal confix
    • Syntax coloring
  • REPL: read, eval, print, loop
  • prompt_toolkit

Text is More Complicated Than You Think: Comparing and Sorting Unicode (by @morganwahl)

How to Make a Good Library API (by @flaviojuvenal)

A talk with some great tips for making better APIs.

An API should make the simple easy, the complex possible, and the wrong impossible.

  • Video
  • Slides
  • Simplicity, flexibility, consistency and safety
  • Focus on the 90% of use cases - this should be easy from the user’s POV.
  • Be flexible enough to handle the remaining 10% (inheritance, forking, etc).
  • Pitch your library to your users in the README file, show sample code
  • Know your users so you can figure out the 90-10 breakdown
  • Progressive disclosure -> good defaults -> make assumptions (e.g. Google homepage focuses on search)
  • Avoid cumbersome inputs
  • Abstract away complexity: focus on what instead of how
  • Brevity: good abstraction reduce clutter
  • All abstractions leak
  • Multiple options of integration: continuum from unsolved to overkill
  • Increase granularity: separate concerns
  • Flexibility: attributes or get method?
  • Be Pythonic

Library UX: Using Abstraction Towards Friendlier APIs (by @makmanalp)

  • Video
  • UX: user experience and usability
  • Enable and empower the user to do cool stuff
  • Good UX reduces mistakesa, minimizes distractions, makes complex tasks routine
  • Abstraction: hiding details in a controlled way
  • Write the press release first: then decide on the appropriate level of abstraction
  • Imagine your library is done: how would the user’s code look?
  • DRY: don’t repeat yourself vs don’t refactor yet
  • Prefer duplication over the wrong abstraction
  • Abstractions should be a hood, not a wall