My New Experiment: Journaling All the Things

At CocoaConf I attended a session from my fellow Big Nerd Ranch coworker, Mark Dalrymple. In this session he explored the questions we ask when looking for bugs — or more specifically their solutions.

At one point Mark showcased a text document that in glorious detail documented the assumptions, questions and answers he was going through to solve a problem. Now, this wasn’t a document Mark made for the talk, it was from a real journal entry he had. He was Rubber Ducking but documenting the discussion like a court reporter.

If you ever work with Mark you’ll quickly discover he is a relentless notetaker. This is just one more example of how it can pay off.

  • Need to step away to work on something else, here is a document to reload your context.
  • Need to invite someone else on to help solve the problem, here is your knowledge transfer.
  • Want to write up a blog post to help others in the future, here is your draft.

I left the session very inspired. As a result, for this week, technically my vacation week but I’m working on side projects, I’m starting an experiment where I try to emulate Mark’s journaling habits as best I can. I have 3 documents at the moment:

  • Daily Journal — Mostly flat list with GOALS for the day and then ACCOMPLISHMENTS of what actually got done at the end. If something in the list has notes in and of itself, it’s hot-linked to those on their own wiki page.
  • Company Journal — Documenting the efforts I’m putting into my side project and the company that encapsulates it.
  • Tech Journal — Starting with Apple, here is where I’m collection my thoughts, issues, and bugs relative to Apple technologies. I expect to make more for other stacks like web in the future.

I’m using VoodooPad for the actual files/wikis themselves. It works well letting me organize like a wiki and can handle screenshots too.

We’ll see how I hold up. I want to give it my all for at least a week and then will do a retrospective as to how it’s working out. There are challenges (like my current typing speed) but lots of potential benefits too.

Update: More from Mark’s own blog.

Do you journal like this? Any tips or other feedback? I’d love to hear it. Message me on Twitter @zorn or via email: mike@clickablebliss.com.

Isolating Mac Application Menu Behaviors

A Place for Everything, and Everything in It’s Place

My side project is a Mac app and last week I was working on a small story about sending feedback.

Send Feedback under Help Menu

As a user, I want to be able to Submit Feedback via the Help menu, So that I let the developer know what I’d like changed.

Acceptance Criteria:

  • Under the Help menu there should be option to submit feedback.
  • Upon selecting this menu item a new email will be open.
  • to: mzornek+storyteller@gmail.com
  • subject: [Storyteller Feedback] [1.0(101)] — that is the version number and build number

This was easy enough to get working but I wasn’t in love with my first implementation. If you read up on the Menu documentation for macOS you’ll find out application menus will follow the Responder Chain . A responder chain of a document-based application looks like this:

responder chain of a document-based application

Now while this is a document-based application this behavior is an application-level behavior. The best spot to put it is in the AppDelegate but I don’t like polluting that class.

My new solutions helps improve the situation in lieu of the framework’s design constraints. I still have the IBAction inside the AppDelegate but it now forwards the behavior to another object that is more isolated, with a single responsibility and is easier to test.

// AppDelegate+SubmitFeedback.swift
import Cocoa

extension AppDelegate {
    @IBAction private func submitFeedback(sender: AnyObject?) {
        submitFeedbackService.submitFeedback()
    }
}


// SubmitFeedbackService.swift
import Cocoa

protocol URLOpener {
    func openURL(url: NSURL) -> Bool
}

extension NSWorkspace: URLOpener { }

struct SubmitFeedbackService {

    private var to: String {
        return "mzornek+storyteller@gmail.com".urlEscape()
    }

    private var subject: String {
        return "[Feedback: Storyteller \(versionString)] ".urlEscape()
    }

    private var versionString: String {
        let appVersion = NSBundle.mainBundle().appVersion
        let bundleVersion = NSBundle.mainBundle().appBundleVersion
        return "\(appVersion) (\(bundleVersion))"
    }

    private let urlOpener: URLOpener

    init(workspace: URLOpener = NSWorkspace.sharedWorkspace()) {
        urlOpener = workspace
    }

    func submitFeedback() {
        let urlTemplate = "mailto:\(to)?subject=\(subject)"
        guard let emailURL = NSURL(string: urlTemplate) else {
            assertionFailure("Email should parse fine.")
            return
        }
        urlOpener.openURL(emailURL)
    }
}

private extension String {
    func urlEscape() -> String {
        guard let result = self.stringByAddingPercentEncodingWithAllowedCharacters(NSCharacterSet.URLQueryAllowedCharacterSet()) else {
            assertionFailure("Could not escape string for URL")
            return self
        }
        return result
    }
}

// SubmitFeedbackServiceTests.swift

import XCTest
@testable import Storyteller

class SubmitFeedbackServiceTests: XCTestCase {

    func testCallingSubmitFeedbackOpensAMailtoURL() {
        let mockWorkspace = NSWorkspaceMock()
        let service = SubmitFeedbackService(workspace: mockWorkspace)
        service.submitFeedback()
        XCTAssertNotNil(mockWorkspace.lastOpenedURL)
        XCTAssertEqual(mockWorkspace.lastOpenedURL!.scheme, "mailto")
    }

}

class NSWorkspaceMock: NSObject, URLOpener {
    var lastOpenedURL: NSURL?
    func openURL(url: NSURL) -> Bool {
        lastOpenedURL = url
        return true
    }
}

Feels cleaner to me but I welcome feedback. I also suspect SubmitFeedbackService will evolve in time as there is other communication needs in the future.

PS: I hope to share more about the implementation of project in the future. I know there is a void of Mac application programming discussions going on out in the web. I will try to help out with my own journalling the best I can. Questions welcome.

CocoaConf DC 2016 Recap

Had the pleasure to attend and speak at CocoaConf DC this past weekend.

CocoaConf is a touring training conference for iPhone, iPad, and Mac developers. We bring some of the best authors, trainers, and speakers to the most passionate, engaged developers in a region—together, they make magic!

CocoaConf draws anywhere from 100-120 developers. It’s a very nice, comfortable size. Large enough to host a diverse collection of personalities and ideas, but small enough not to feel overwhelming. People actively mingle and you get to meet lots of new faces without much effort.

This was my third CocoaConf, and first as a speaker. My own talk was at the end of the first day and I spent ample time the previous weeks preparing to avoid the need to do last minute slide updates and miss sessions — and I’m glad I did so.

The sessions were really good at this CocoaConf. Sure it helps that iOS 10 is just out and there is still lots to learn, but even the talks that were version agnostic, covering patterns, architectures and bug hunting skills all got my brain spinning with ideas.

One cool benefit of my work scheduling is now I have a week of stay-home vacation and I can hopefully direct that post-conference enthusiasm towards my side projects and some extra experimentation. Specific items on my list:

  • Do more interactive prototyping of my side project and follow up with some user interviews.
  • Do some experimentation with Perfect to build a simple Swift API and host it on Linode.
  • Continue to polish up my RanchWeather app and start a blog series reviewing the code patterns.
  • Do some experimentation with Twilio authentication in preparation for a web app project.
  • Inspired by the journalling abilities of MarkD, dedicate the vacation week to a journaling experiment: Daily Journal, Project Journal, Tool Journal.

As for my talk, I think it went very well. One thing I really like as a speaker is the conference not only has a session review system but they encourage submissions of reviews with a raffle for prizes at the end so you get a lot of feedback. Most of my talk’s feedback was very positive and I appreciate the criticisms, both good and bad. Always room for improvement.

So yeah, if you are considering attending or speaking at a CocoaConf, do it. It’s very rewarding and worthy of your time. If it’s on the east coast you’re more than likely to see me there too — and if so, say hi!