28 Jun 2016
Presentation Patterns is 228 pages of information about how to give a good presentation. What’s most interesting about this is that only 16 of them need to be read in serious depth. The rest are browsed, searched for, cross-referenced, and looked up as you go, like a choose-your-own-adventure book meets tvtropes.org. Even though it was a bit tedious at times, I found myself thoroughly enjoying the act of keeping five or more fingers jammed at relevant sections, all while flipping back to the glossary yet again to decipher more terminology.
What stood out to me the most was the section in the introduction “Origins”, in which the authors talk about their experience in the software development industry, and how it has affected their view on giving effective presentations. What results from this background is a book that reads a lot like documentation for a software library or programming language — a high level overview section, how to use it, why it was created, and finally, an exhaustive listing of both common recipes and low-level implementation instructions. This creates a learning experience familiar to software developers in particular. You start by clumsily browsing self-referencing jargon that you don’t yet understand, until you find a small, clear example that terminates and no longer needs you to look for information elsewhere to understand it. You can keep nesting into topics like this until you have a grasp of the vocabulary necessary to begin comprehending the full picture. Isolated examples of what to do and (more importantly) what not to do, creates a wonderful book that turns what should be a dense topic into something you can reference as you need it.
I swear, this guy actually said this.
I really appreciate the effort it takes to shape such a complex topic into a simplified aid, to be used when the time comes, and returned to your bookshelf for another visit in the future, when you need it.
Below is a summary of those critical 16 pages, and a few examples of what constitutes the bulk of the material in the book to help you better understand it’s uses and application for you.
Main Takeaway Number One: Be Prepared
This gets repeated throughout the book, and for good reason. When your full-time job is giving presentations, the chances of having something go wrong is
- Much higher
- Much more damaging to your bottom line.
If you’re giving a presentation at work for eight people, and you slap something together during your lunch hour the day of, you can either reschedule the talk, or just go ahead and wing it. If you’re a professional speaker (as the authors are), and you have a laptop hard drive die the night before a talk, you have much larger problems to deal with if you aren’t completely prepared. For those of us who give a couple talks a month (or year), this isn’t so much important as much as it is to avoid going meta when the opportunity arises to make a clumsy excuse about how “I whipped this thing up a couple hours ago”. I really enjoy getting introduced to many of the anti-patterns, as they rang very familiar to me, an amateur speaker. A great way to get quickly introduced to the main concepts of this book is to read more anti-patterns (highlighted in red) than patterns (highlighted in blue).
It’s also a lot more fun to do it this way, too.
Main Takeaway Number Two: Lurk More
Links like the one I made above to the “going meta” anti-pattern are where the book really shines. The book is absolutely full of these references. Every paragraph seems to have one or two of them (styled like hyperlinks, no less) that constantly tricked me into thinking that I could click them. This book really does feel like it was printed to paper second, after being crafted as a web-based document first. As you get familiar with the basics, you are introduced to more and more nuanced material to help polish your talk as you develop it. This is no accident. In fact, the gradual consistency pattern recommends you do just that. The authors have not only given you examples upon examples to reference, but also manage to dogfood their own methodologies throughout the text, creating a single, large example of how to effectively use many of the more “core” patterns featured in the glossary. By studying the overall design of the book, you seem to absorb some of its best parts through osmosis.
Main Takeaway Number Three: Execution Matters
The authors come to warn you that as you craft your presentation, you shouldn’t take a pattern or recipe at face value. Since presentation patterns are broken up into small, focused chunks of composable contents for a talk, it can be difficult to convey the essence of the pattern in any format other than a short example or two. These examples tend to feature aspects of the pattern or anti-pattern that correlate with a familiar instance of them. Just because your talk does not feature excessive swinging and circling with a green laser pointer does not mean that your talk isn’t suffering from the same root cause that inspires lesser speakers to reach for the oft-abused speaker’s aid.
The moral of the story is, each example given is just that, an example. The kernel of wisdom comes in how you apply it. An egregious example would be in the case of a poorly executed pattern. If you decided to use the make it rain pattern to serve as an ice breaker for a tough crowd, you’d be smart in doing so. Unless that meeting is for a board of directors to brainstorm how best to respond to a hostile takeover, then it’d be best to go another route.
In Close
No matter how far you progress in this book, never forget the first thing they teach you in a beginner’s public speaking class in college. Know your audience. Then, craft an outline. Pick and choose from your now well-versed arsenal of patterns with taste. Practice your talk, and the rest will work itself out. This book is useless without a proper foundation and work ethic, as it can only open the door for you. It’s up to you to walk through it.
25 Jul 2015
Squashing pull requests is a common theme in many software projects that use git for version control. I won’t go over the reasons why in depth, but rather focus on a workflow that can help address a lot of the controversy around squashing pull requests into a single commit.
Let’s say I’m creating a new feature on a branch, and like many developers, I choose to commit early and often. Every new chunk of a feature triggers a commit and a push to my branch, including unrelated commits that clean up documentation and comments. By the time I’m finished, I may see something like this.
09:05:24 (cool-new-feature) ~/code/js/project-name
$: git lg 6
ee11b36 - style(grunt): Sort tasks alphabetically (2 minutes ago) <Droogans>
aeef141 - feat(search): Autofocus on search box (8 minutes ago) <Droogans>
63c7f63 - refact(search): Clean up some unused code (34 minutes ago) <Droogans>
7282f5f - chore(tags): Alter tags (1 hour ago) <Droogans>
077e361 - feat(search): Outline WIP (2 hours ago) <Droogans>
42354f2 - Merge pull request #45 from Droogans/old-feature (1 day ago) <Droogans>
Although this represents a clean commit history, the inclusion of the phrase "WIP" in commit 077e361 definitely suggests that some cleaning up is in order. However, lumping all of this work into a single commit might strike others as heavy handed since there are unrelated fixes to documentation and some build automation.
Making -squashed Branches
A visual summary.
A simple way around this is to include a branch for both the original pull request (warts and all), and another branch that officially gets merged. Here’s the same example from above continued in this way.
First, I push up the cool-new-feature branch.
09:21:10 (cool-new-feature) ~/code/js/project-name
$: git push origin cool-new-feature
From there I open a new pull request and ask for a review. Once it gets signed off, the maintainer asks me to push up the squashed version for merging.
14:48:52 (cool-new-feature) ~/code/js/project-name
$: git checkout -b cool-new-feature-squashed
Switched to a new branch 'cool-new-feature-squashed'
14:48:56 (cool-new-feature-squashed) ~/code/js/project-name
$: git rebase -i 42354f2 # this is the merge commit from latest master
Waiting for $EDITOR...
From there, my editor would display the list of five commits I’ve made in this branch. I would tag probably do something like this for my summarized pull request.
pick ee11b36 - style(grunt): Sort tasks alphabetically
pick aeef141 - feat(search): Autofocus on search box
squash 63c7f63 - refact(search): Clean up some unused code
squash 077e361 - feat(search): Outline WIP
pick 7282f5f - chore(tags): Alter tags
# Rebase 42354f2..ee11b36 onto 42354f2 ( 5 TODO item(s))
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
This reorders the commits so that some necessary (but still unrelated to the feature directly) is done first, then places any and all code related to the feature (including refactoring) into a single commit. Finally, a useful but unrelated commit is included at the end.
The commit in the middle prompts me to make some decisions about how I’m going to name these commits. I change the commit message for the ugly “WIP” outline commit that I made at first, and replace it with something well-formed and succinct that summarizes the entire feature. Below that, I leave the squashed commits as a foot note for maintainers to read, using the opportunity to highlight what is going on in detail should they need to know later.
# This is a combination of 3 commits.
# The first commit's message is:
feat(search): Cleaner search results
This addresses some issues with search results not displaying the
most important information first. Stop showing so many details about
the search result web site and focus on highlighting the content
instead to give users a better idea of what the result contains.
# This is the 2nd commit message:
refact(search): Clean up some unused code
`search-result.html` is better included inside of the main search
table directive, as they seem to be doing a lot of the same work
in two different places. This also presented an opportunity to
introduce a new service for search results, instead of doing
everything in the search controller.
# This is the 3rd commit message:
feat(search): Autofocus on search box
You had to click the search box to start searching, now you just type.
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date: Sat Jul 18 14:49:01 2015 +0300
#
# rebase in progress; onto 42354f2
#
# Changes to be committed:
# modified: app/src/search/controller.js
# modified: app/src/search/controller.spec.js
# deleted: app/src/search/search-result.html
# modified: app/src/search/search-table.html
# new file: app/src/search/service.js
# new file: app/src/search/service.spec.js
#
This is really useful because it accomplishes a lot of good things at the same time.
- There is a verbose log in
<branch-name>
- There is a clean, merge-friendly log in
<branch-name>-squashed
- Commits made early and often can be sloppy, cryptic, and frequent
- Commits squashed together in the squashed branch are documented at squash time, allowing developers the flexibility of doing all clean up work at once, when they know the feature is good and ready for merging
- You allow the developer to focus on one thing at a time — getting the feature working first, and then later, getting the feature well documented for others to look back on in the future. It can be distracting to constantly switch between those two mindsets
Once I’m finished, I do a quick sanity check to make sure everything looks alright.
14:51:33 (cool-new-feature-squashed) ~/code/js/project-name
$: git lg 4
68bd51e - style(grunt): Sort tasks alphabetically (1 minute ago) <Droogans>
8bd8771 - feat(search): Outline WIP (1 minute ago) <Droogans>
f61bbe2 - chore(tags): Alter tags (1 minute ago) <Droogans>
42354f2 - Merge pull request #45 from Droogans/old-feature (1 day ago) <Droogans>
14:51:38 (cool-new-feature-squashed) ~/code/js/project-name
$: git push origin cool-new-feature-squashed
I open a new pull request, close the first one, and merge it.
Keep in mind you’ll want the project documentation to contain information to contributors that any branch that has been merged can have -squashed removed from the end of it to reveal a verbose change log from the developers rough draft of the feature.
13 Jun 2015
Here’s a simple habit that can make working with numbered lists in markdown much simpler, especially if you’re still mentally figuring out the order of the list as you’re typing it.
Typically, numbered lists in markdown are demonstrated in a simple, straightforward fashion.
1. A list
2. Where order
3. Matters greatly
4. And could change
5. In the future
Now, should I need to add a step that I forgot, I’d have some unneccessary editing to do.
1. A list
2. Of important things
2. Where order
3. Matters greatly
4. And could change
5. In the future
The second two becomes a three, the second three becomes a four, and so on. It’s a subconcious thing – I believe that most writers have a desire to number their lists appropriately, and will want to see them fixed right away. It hinders thinking if the list is numbered incorrectly (at least it does for me). Once the list looks pretty again, thinking resumes. And now, another entry is placed between numbers two and three, and the cycle continues.
Here’s a better way.
0. A list
0. Of important things
0. Where order
0. Matters greatly
0. And could change
0. Very easily
0. In the future
This will render as the same numbered list, and appears as a neutral “increment” value of zero. Of course, inserting or rearranging this list is trivial.
06 Feb 2015
This review is dedicated to my brother, who got me a copy of this album, urging me to listen to it. I wasn’t supposed to judge it, and simply listen to it with an open mind and let him know what I thought. I did, and I guess the best way I can think to prove this to him is to write a review of Mark Ronson’s latest release, “Uptown Special”.
Before I begin, there are two things you should understand about my music listening habits, both of which are likely attributed by my upbringing preforming classical violin in middle school and high school. First off, this album is far too new for me to be listening to it, being that my standard is to wait anywhere between 9 and 12 months after an album is released before spending any time listening to it. When you are spending large chunks of your free time rehearsing 200 year old music, listening to music from three years ago is suddenly so new, even if the rest of the world has long moved on.
This can also be really helpful in cases where critical reviews are dominating search engine results immediately following the release, which can muddy my perception of the album after reading another’s take on it. This is a big deal to me. Had I listened to, say, King of Limbs right after release, I probably wouldn’t have given it more than two or three listens before succumbing to the temptation to “supplement” my opinion with that of popular sources’ review.
However, I waited about a year, allowing me to engage in my second odd quirk in my listening habits, again, forged by my years in the orchestra. I listen to the same album (or sometimes, a group’s entire catalog) for, on average, four to six weeks. I work in software development, and in that capacity I spend a typical day with about five hours of solid listening time. To be conservative, I’ve listened to this album, on repeat, probably 100 times. I have sonically etched this album into my brain’s auditory stores, available for high-quality playback for up to six months. All I need is a quiet room and a little bit of time. So I feel my opinion on this album is coming from place beyond a simple “impression” review and more “I have this album basically memorized”.
You may wonder how the math adds up there, for those who decided to do a quick back of the napkin estimate of my claims of listening to this album one hundred times. The album is much too long to listen to that many times in two weeks! You’re right, it is. However, I didn’t listen to the entire album one hundred times. I listened to the entire thing maybe twenty times or so. After just a few days of listening to this album, I decided to cut out some tracks that I felt were added simply to justify the album’s existence from a production standpoint. Those tracks were conveniently located in a cluster; tracks three, four and five.
It really upsets me that the smash hit single of the release, “Uptown Funk”, has, at the time of writing, nearly 184 million views on YouTube, while many of the really engaging parts hang in at around two thousand hits each. I mean, sure, I get it. You have to have something that will catapult the rest of the material into a place where it can get produced, publicized and performed, and in that sense Uptown Funk does a great job doing that. What it doesn’t do a great job of is fitting in with the rest of the album. Speaking of that, Mystikal’s half-stepping insult to James Brown’s raspy style is so far removed from the other tracks as to be utterly dumbfounding. Rounding out this trio is an overly intense, too-disco sound of “I Can’t Lose”. With these, you have what record executives call a solid offering, and what a Pulitzer Prize winning author and lyricist calls a distraction.
What I can’t understand is, if the album has a supposed R&B influence of the 70’s and 80’s, why does that influence only appear on the tracks that don’t seem to fit in with the rest of the album? Why does the rest of the album sound like it was made by a progressive rock band with a good ear for electronic interludes? Why do the lyrics go from parties, dancing, and a general sense of being a standard pop record to entering very strange world of reflecting on your deserted upbringing in privileged Los Felix, New York? This becomes more troubling when the rest of the album pushes on into a life of gambling, prostitution, and dealing heroine in Las Vegas.
This album sounded like it set out to be a very bold, ambitious abstract on living a questionable life in the desert, and ended up being half of that with some pop singles tacked on. What a disappointment. If you have a haunting interlude by Stevie Wonder sprinkled throughout your album hinting at some serious trouble nine exits North of Las Vegas, you shouldn’t squander that with cheap grabs at the Hot 100. But who am I to judge. Without those singles, I probably wouldn’t have found this excellent group of eight tracks, a solid 27 minute ride that will definitely stay on repeat with me for at least the next few weeks. If I were to review just those eight tracks, this review would easily earn four stars out of five.
Favorite Tracks:
- Crack in the Pearl, Part II.
- Leaving Los Felix
- In Case of Fire
If you liked this album (namely, the parts I didn’t delete from the track listing), you might enjoy Miami Horror’s Infinite Canyons.
27 Jan 2015
This is my fifth year writing software. As I continue my development in the trade, I find myself spending more and more time interacting with people who’s level of contribution now exceeds that of an “individual contributor”. They are much too talented to be writing any more code, so their superiors would like to say. Their time would be much better spent discussing the problems that some given software is trying to solve, and ideally, never write any to begin with. In those cases where software is needed, they spend their efforts scaffolding out initial solutions, architecting the patterns for others to fill in with details. I would argue that these all play a part in a successful version of the software development life cycle.
I have no issue going on the record by publicly stating that I have no interest in being a member of this group. In fact, I’ll go as far as saying that the only way to stay truly sharp in the ever-evolving world of software development is to periodically reset your career to that of a junior hire every couple of years. Any analogy that you might construct to convince me otherwise is likely to apply poorly to writing software. We are not generals in a war, where “boots on the ground” can’t be wasted on the likes of our best and brightest. Oftentimes, there isn’t a clean way to truly solve (or even understand) a problem without becoming the entry-level developer who invariably gets tasked with that whole “details” part of the process. I find it odd that we leave our best and brightest to identify the obvious parts of the problem, while leaving the costliest, most error prone mistakes to be made by those who are in the prime of their mistake-making part of their careers.
For an example, take the common case: business software. At the highest, highest levels, there is a need for some payroll system to be put in place for a new company. For someone at a director level, there is a tax issue preventing them with going through a typical payroll servicing company. For an architect, there are tax disadvantages by using pre-fabricated payroll software, so it’ll need to be coded in house. At this point, much of the hard work is done, in a sense. The only thing left is to actually make that list of exceedingly more detailed requirements into the most detailed requirements — computer software. Compare this with something like research, where those at the highest levels decide there is a practical business need to build self-driving cars. A director discovers that the technologies behind this don’t exist yet, or at best, are new, unvetted, and rough. Where do you begin with those requirements? No amount of architecting can suddenly make computer vision easier. Those are hard details, and they must be orchestrated in a way that makes sense when conforming to something as massive and complex as the motor roadway laws of California.
A great developer will be able to see the forest through the trees, while running through it with a group of four people. Obviously, you can’t do it forever, but again, many analogies fail here. It’s a lot like hunting, except the barrier to exit is much, much lower. You can be a great hunter, and know where the biggest game tend to gather, but your insights will only take those doing the actual hunting so far. When you’re no longer the one stringing the bow, it’s easy to forget that the hardest part of hunting is “don’t miss”. If you find yourself suddenly supporting a village too large to do the hunting yourself anymore, it may be time to start designing better bows and arrows for them to use.
What do you have to lose in a skill like software development? Your ability to type? Your eyesight? Those things last for seventy years or more in a healthy citizen living in a first-world country. The only major loss you face as a real threat is your ability to stay active in a world that is dominated by the new technologies, authors, tools and workflows that can too easily slip from your grasp as you become too senior of a developer.
