Development

日本 (Japan) & Orbital Periods

My littlest sister is currently in 日本 (a.k.a Japan), embarking on her Japanese Studies major work for university. I’m proud of her — and, today is her birthday!

✨ 🍰 ✨

To celebrate the occasion, I’d like to share some images that I took while on a trip to Tokyo, Japan, on behalf of Heroku.

Japan will always be near and dear to my heart, for many reasons, but Heroku (which I joined back in 2011 and departed within the past few years), will always be the strongest reason for my affections for the nation / land / territory / people / culture.

const heroku = ('hero' + 'haiku')

One of my proudest professional accomplishments, thus far, has been helping to inform the design of the following image—

Python Haiku  by  @seaofclouds  (Todd Matthews).

Python Haiku by @seaofclouds (Todd Matthews).

Anyway, here are a carefully curated selection of the images I captured during that short trip. I was using a Leica M240 with a brand new 35mm Summilux (f/1.4) lens. These are arguably some of the best images, image-quality–wise, that I’ve ever taken. Thanks for listening, and enjoy the show! and— Happy birthday, Brittany!


Ethical lessons from the open source community

Since ~2011, I’ve focused the majority of my time on open source software. Only sometimes, lately, do I take a moment to sit back and reflect on lessons learned (often the hard way).

This is always a useful exercise, as I view the open source software community as at the fore-front of many social inventions; we’re effectively, in my opinion, the best self-organized, distributed force on Earth. I’m sure, in my ignorance, other groups hold themselves in similar regard. But, it is a fruitful exercise, nonetheless, to view our community this way.

Much in the spirit of The Hacker’s Manifesto, I am sharing here a concise, inconclusive list of moral principles that I have extracted from my collective experiences in the open source community.


Approach all others with respectfulness.

Be cordial or be on your way.


Never expect anything, in return.

Others may not have the bandwidth to process the valuable information you’re offering, or inquiring about. Never expect anyone to even answer your question or respond to your ticket.

Be thankful, when it does happen.


Access to information (e.g. documentation) allows
our efforts to scale, more so than any other factor.

I gave a talk about this.


The needs of the collective are (usually)
more important than the needs of yourself
.

The exception makes the rule.


Sustainability via collective interest
.


Your project might “die” one day, fading away into nothingness, if no one else is interested.
The world may move on from the trend that is making your library popular.

All software is transient.


Entropy is good
.

Web Framework Classification and Clarification

The Python ecosystem is filled with various web frameworks, including my own, Responder.

In this post, I seek to organize and classify some of the various frameworks into distinct categories.

 

Category A: First-Class Frameworks

Flask

Flask should be your go-to for almost any application you're building for the web today.

Django

Django is an excellent choice for building web applications as well, particularly those that require an admin interface.

Pyramid

Pyramid is a great choice for those that like to get their hands a little dirty when building their applications.

Category B: Second-Class Frameworks

Responder

Responder makes a lot of sense if you want an alternative to Flask, don't use a lot of plugins, and like using cutting-edge technologies.

Others

Other web frameworks, like Falcon, fit into this classification as well.

The primary purpose of this post was to clarify the positioning of Responder, and I believe this post accomplishes that goal.

Kenneth Reitz’s Code Style™

The Requests codebase uses the PEP 8 code style.

In addition to the standards outlined in PEP 8, we have a few guidelines:

  • Line-length can exceed 79 characters, to 100, when convenient.

  • Line-length can exceed 100 characters, when doing otherwise would be terribly inconvenient.

  • Always use single-quoted strings (e.g. '#flatearth'), unless a single-quote occurs within the string.

Additionally, one of the styles that PEP8 recommends for line continuations completely lacks all sense of taste, and is not to be permitted within the Requests codebase:

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

No. Just don’t. Please.

Docstrings are to follow the following syntaxes:

def the_earth_is_flat():
    """NASA divided up the seas into thirty-three degrees."""
    pass
def fibonacci_spiral_tool():
    """With my feet upon the ground I lose myself / between the sounds
    and open wide to suck it in. / I feel it move across my skin. / I'm
    reaching up and reaching out. / I'm reaching for the random or
    whatever will bewilder me. / Whatever will bewilder me. / And
    following our will and wind we may just go where no one's been. /
    We'll ride the spiral to the end and may just go where no one's
    been.

    Spiral out. Keep going...
    """
    pass

All functions, methods, and classes are to contain docstrings. Object data model methods (e.g. __repr__) are typically the exception to this rule.

Thanks for helping to make the world a better place!

Apple Pencil Note-Taking: Why You Should Use Apple Notes, actually.

I'm a bit of a digital ink snob. I've been writing actively with digital ink for over 10 years, and there's a lot of things that most developers get wrong when developing note-taking apps. There's a plethora of them available for the iPad Pro & Pencil — only two of which I find to have acceptable inking implementations.

The iPad inking world

The first inking application we'll review is very popular, and is the typical choice for digital ink snobs (such as myself): Notability. It costs $10.

Notability has excellent, responsive, and fast, and (very) pressure-sensitive inking. It allows you to categorize your notes into a single bucket of folders (this isn't the most polished experience), is vector–based (infinite zoom) and features an infinite canvas. It is great for drawing sketches or doodles as well as simply writing down text. Notability's pressure-sensitivity is highly adjustable and configurable, but by default, the pressure gradient goes from minute thickness to tremendous thickness. This is considered to be a feature, to many, as you don't have to dive into a menu to have a totally different thickness in your pen — you just press harder (or much lighter) than usual. In addition, it also offers a Mac app that uses iCloud syncing to seamlessly view (and potentially edit) your notes on your Mac. 

Another app that is less well-known, but extremely well made is Note Always. Note Always features a great non-variable thickness (aside from velocity) pen,  with a vast number of colors to chose from, as well as a small assortment of pre-determined thickness. This app is not pressure sensitive, which I find to be surprisingly enjoyable, when writing. This "feature" allows your text to look much more uniform as you write, and can make your handwriting appear to be slightly better than it truly is. 

My favorite feature of Note Always, which I have yet to see anywhere else, is the ability to map your finger to stroke selection or erasion. This is extremely nifty, as it allows you to simply run your finger over a section of notes and move it anywhere you please (or change it's color, etc). This is the reason I love this app, and have been using it for a long time — both to plan, design, get things done, and simply explore the contents of my own mind. 

There are two categories that you can file any note-taking app in the App Store into:

  1. Text-first design. Apps like Bear and Evernote fall into this category. They typically focus on organization as a feature. 
  2. Ink-first design. Apps like Goodnotes, Notability, Notebook+, Neebo, Note Always, etc fall into this category. They typically have categorization as a secondary consideration, and text is just something they slap in there, if they do it at all. They then focus their development efforts on inking technology and workflow optimizations — in which they are typically (which some notable exceptions) lagging behind in. 

Apple Notes

Apple Notes is the only app that falls into both of these categories (text-first design, ink-first design) without making any compromises. OneNote also fits into both categories, but text suffers a bit in that application, unfortunately. You wouldn't want to use it without the inking features, as the movable text boxes surround everything you write. 

Apple Notes is one of those apps where I tried it for 5 minutes, for inking (I've been using it casually for text notes for years), and immediately dismissed it. It lacked all the things I was used to in my third-party applications: there's no ability to adjust the thickness of the pen, for example. The pencil, while novel, seemed… weird. It just seemed like Apple threw together this app haphazardly and was like "yay look here's an Apple Pencil demo for y'all!". Upon futher examination and exploration, however, I now find the opposite to be true. 

Apple Notes is hands-down the most well–designed, thought–through note taking app available for the iPad Pro. It is exceptionally well designed, and if you leave your preconceptions about what a note–taking app should do, I think you'll find yourself agreeing with me, once you give it a real try/chance. 

Allow me to present my case:

  1. Un–obvious superior inking. As I mentioned before, there are only two apps on the App Store which I consider to have acceptable inking performance: Notability and Note Always. OneNote gets an honorable mention, but it really fits in with another category of application. All others have inferior inking available, or they significantly lack in other areas (e.g. workflow, note organization, etc) — enough to dismiss them as viable options entirely.

    P.S. I've literally purchased every single note-taking app on the App Store, and have given them all a non-dismissive amount of time to show their colors. Most are truly total junk. Design matters. And I don't mean visual design — I mean UX design, thoughtfulness, pen responsiveness, etc — the truest form of engineering.

    The inking available in Apple Notes, while very unconventional, is actually hands-down the most well-engineered inking system I've ever encountered.

    You can't change the size of the pen. There is one pen. It is a pen.

    Not only is it a pen, that presents itself as having static thickness, but it is a modal pen (capable of smooth thickness gradients) that is both pressure sensitive, and also helps assist your handwriting by being of uniform thickness at the same time. I can tell you that a significant amount of engineering and thoughtfulness went into this pen — far more than any other app available. And, if you really use it as it's designed, you'll be blown away. It's the best pen I've ever used. I wish I had one in real life. But, I do — I have Apple Notes. Digital is real life, today.

    One design consideration they engineered is quite un–obvious to most users, but doesn't go unnoticed to people who have been digitally inking for 10 years. If you start a stroke with medium pressure, a medium line is drawn. Then, if you finish the stroke with firm pressure, Apple Notes knows that you intended for the entire stroke to be of the firm pressure's bold thickness, and it goes back and changes the rest of the stroke to match. This feature is very intelligent too — if you're drawing, for example, you'll present a lot of pressure gradients to Apple Notes, and it will still render them as expected. They're doing some very advanced analysis here to determine whether or not to back-fill the pressure of a stroke. I'm extremely impressed.

    In addition, the pen's thickness works extremely well for writing of all sizes. I tend to write as small as humanely possible, at times, and the precision of the strokes and the clarity it renders is unmatched by all other software and hardware options available. If you write large, you'll find that the pen renders your strokes quite nicely too. It's the world's first true "universal pen".

     Notice that there's no settings for the pen — no adjustments can be made. A strong design lesson that was instilled upon me at my tenure at Heroku was "Remove levers, even if it's very expensive to do so". In Apple Notes, there are no levers. This is not a testament to laziness — in fact, it is quite the opposite. Extraordinary efforts were put forth to ensure that no configuration is needed in the first place. 

    So, if you dismissed Apple Notes because you didn't see a bunch of settings, think again.

 

  • Excellent organizational abilities. Apple Note's folder (and sub-folder) structure allows you to build a very complex (if needed) heirarchy for storing your notes. The only application that has a comparable organizational system is OneNote. 
  • (Perfect) Syncing. Instantaneous real-time syncing of all notes to all devices. First-class client available on all Apple devices. Can't complain there, in any way.
  • OS Integration. Press your Apple Pencil to your lock screen, and instantly create a new note. Who wouldn't want the app that fires up to be configurable? Apple doesn't want it to be configurable, because Apple knows that Apple Notes is simply the best tool for the job. Once there are real competitors in this space (OneNote could be argued to be one), I'd like to think that Apple would make this configurable, but it would require a significant amount of currently non–public APIs to do so. e.g. this ask is not a simple one. 
  • Precise eraser and selection tool. Other apps often have a very imprecise eraser or selection tool. Apple Note's uses the Apple Pencil for these things, and is stroke-based, so erasing just one letter in the middle of a word is trivially easy. In some apps, that's impossible. A nice bonus feature of the common selection circle is that you can simply draw a line through a line of text, and it will select that text automatically. Well done!
  • Screen orientation perfection. In some apps, there's a dichotomy between portrait and landscape mode. In Note Always, the paper you're using actually determines the orientation. There is no switching between modes, without changing your paper, and possibly losing sections of your notes. In Apple Notes, screen orientation effects only the presentation zoom level of the width of the page (which is fixed). Apple Notes lacks the conventional pitch-to-zoom feature (as does actual paper), but you can easily change between different comfortable zoom levels by changing into fullscreen–landscape, landscape, or portrait mode. Very nicely done and seemless.
  • Excellent pencil tool. At first glance, the pencil tool seems childish in nature, but in reality, it is the most advanced pencil emulation I've ever come across in a note-taking app (Sketches Pro has a better pencil emulation, but it's a drawing app, with a totally different use case (and many, many configuration options). It works very well for handwriting, as well as drawing. It's an excellent tool for embellishing your notes, and I have to admit, I've fallen in love with it. A bonus feature is that if you scrape the side of the tip of the Apple Pencil across your screen, it acts exactly like a pencil would in real life, drawing a long, soft line of graphite down. Very nice touch.
  • The marker tool is not a marker, it's a highlighter. It renders its strokes beneath any ink that has been laid down, and is clearly not a marker after all, but a highlighter. 
  • Color constraints. Apple Notes, in the default "Handwritten Note" mode, gives you an option of five (5) colors. There are no other colors. You cannot change them. This is excellent — let me tell you why. The color selection is as follows: black, blue, green, yellow, and red. The red is not the tone of red I typically invoke, and this bothered me at first, until I took a closer look at it's relation to the other available colors. It's a shade of red that both opposes the shade of blue and green available, as well as compliments the yellow shade. These colors were very carefully thought out and designed, and I'm very impressed — even the order in which they are presented in the UI is clearly carefully thought out. Let me show you what I mean:.
Pasted Graphic 21.png

These are not five random tones. These are tools for thought exploration that interweave and interact with each–other, in subtle ways. Apple Notes is a seriously well–engineered application for inking, and the best one available today

The Downsides

Of course, every tool has it's downsides, and I'll present them here, concisely.

  • No ability to change the color of selected ink. They should add this, in my opinion. If you want a line to be red, you have to draw it red. You learn to adapt to this quickly.
  • No ability to change the orientation or scale of a selection. I don't care about this, as I very rarely want to do this.

That's it. Once again, I have learned a lesson from Apple that I always tend to forget — foroget what you think you want and, with an open mind use what's provided. It's usually in your best interest.

This is why I use Mail.app for my email.

Thanks for your time, and I hope you enjoyed this deep overview of inking technologies, and the shocking conclusion that Apple Notes is superior to any app in the App Store. 


META

P.S. Here are my (sloppy to you, organized to me) notes for creating this blog post, if you're interested. Note the use of the pencil to embellish and augment the pen ink. Also the occasional use of those opposing/complimentary color tones.

page1image1797120.png