Continued from day 1.
How Documentation Works and How to Make it Work for Your Project (by @evildmp)
- 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.
- Style guide
- We read code more often that we write it.
- You can’t maintain code unless you can read it.
- When breaking lines, prioritize readability, not line-length
- When using regexes, always use verbose mode
- Document line wrapping strategy using a style guide
- Read PEP8 every 6 months
- Replace index accesses by variables using e.g. tuple unpacking
- Use specific tools for specific problems: context managers, list comprehensions, operator overloading, etc.
- Use classes to group functionality and data.
- Other talks to watch:
Awesome Command-line Tools (by @amjithr)
… didn’t go to this one either, but it’s worth reviewing. Comes with live coding :)
- pgcli, mycli
- Bringing discoverability to command line applications
- “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
- Minimal confix
- Syntax coloring
- REPL: read, eval, print, loop
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.
- 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)
- 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