All posts tagged with tutorial

Keyboard Shortcuts for Outlook on Mac OS

I’m just going to come straight out and say it: Outlook on the Mac is a pretty decent mail client, particularly if your employer has invested in well-run Exchange and Active Directory services.

Here’s the problem, though.

You’re dealing with new messages in your inbox, and most tasks can be accomplished without taking your hands off the keyboard.

↑ and ↓ take care of navigating through messages.

⌘-R starts a reply, or ⇧-⌘-R (Shift-CMD-R) to reply all… used with extreme caution, please. (“Bedlam DL3?” “Me Too!”)

⌘-N starts a new message. ⇥ (Tab) through the address and subject fields to the message body. ⌘-↵ (CMD-Enter) sends the message.

⌫ and ⌦ are handy, too. I use these most of all.

Now, what if you want to move a message? The keyboard shortcut is ⇧-⌘-M (Shift-CMD-M), which brings up a dialog box to select the folder. (Note that the folder has to exist already. Type a folder name, select it from the list if more than one matches the search string, then press ↵ to move the message.

Moving messages

Unfortunately, that’s a lot of work if you move messages to specific folders frequently. Here’s where we use some built-in Mac OS functionality to create a keyboard shortcut.

When you move a message to a folder by using the ⇧-⌘-M (Shift-CMD-M) or by clicking the Move button on the ribbon, Outlook adds that action to its Move menu items. You can see these by clicking Message > Move and noting the items at the top of the menu.

Move commands

So, first, use either the Move button or the the ⇧-⌘-M action to register the destination in this menu. Note the name exactly as it appears here.

Now go to System Preference > Keyboard > Shortcuts.

Select App Shortcuts, then click the + button to add a new shortcut.

New App Shortcut

For Application choose Microsoft Outlook.app (it may be in the system Applications folder rather than your user Applications).

For Menu Title type in the exact name that appears in Outlook’s Move menu. In my example here it’s “Status (Mailbox - Dorsey, Terrence)”. Your Mac will find this. It’s magic.

For Keyboard Shortcut, type the shortcut key combination.

Shortcut details

Click Add and you’re good to go (assuming no conflicts with other system or app shortcuts).

Now, when you want to move a selected message, just use your keyboard shortcut. As an added bonus, if you ever reorganize folders in Outlook, the app is smart enough to continue routing messages to the right place.

Markdown Links with Template

In Dr. Drang’s recent blog post, Quicker Markdown linking with TextExpander, the good Doctor takes a five-step, TextExpander-powered workflow for creating Markdown-flavored links created by David Sparks (of Mac Power Users fame and notoriety) and improves it with a new, streamlined TextExpander snippet fueled by 18 lines of AppleScript.

The Dr. Drang version programmatically retrieves the URL of the current page in either Safari or Chrome and creates a Markdown link with it. The upside of this method is that you can create a Markdown link without having to switch between apps. The downside is that the web page has to be in the currently selected tab in either Safari or Chrome and you have to supply the link text.

It’s a neat solution. In theory it saves you a context swap between editor and browser, and Dr. Drang’s script is also an interesting starting point for much deeper customization. But I’d like to point out what may be an even better option.

Template Extension

The Template extension for Chrome is a highly customizable utility for extracting data from a web page to the clipboard in a single action.

The key feature is Template’s built-in templating language the enables you to create custom actions that can extract just about anything directly associated with a web page or browser: page URL and title text, meta information in the page, links for all current tabs in the browser and a whole lot more. Check out the Guide for details about all of the template tags and operations you can use.

You can execute any of the templates set up in the extension via a toolbar menu, a right-click context menu or, optionally, a user configurable, template-specific keyboard shortcut.

I’ve only touched the surface of what Template can do, but it hugely simplified many aspects of my work as a technical writer, particularly when it comes to capturing research notes or sharing links. Template has become one of those must-have, first install tools, alongside Alfred, Sublime Text 3 and TextExpander.

I’ll give you a few examples of Template in action just to give you an idea of what’s possible.

Using Template

The simplest template I use regularly just grabs the title of a web page and the URL, something I might grab to paste into an email or Tweet. The template tags are simply {title} {url} and it returns simple strings like so:

Bash $PS1 Generator 2.0 https://www.kirsle.net/wizards/ps1.html

A similar one creates a simple Markdown link using the [{title}]({url}) tags. The results look like this:

[Bash $PS1 Generator 2.0](https://www.kirsle.net/wizards/ps1.html)

Template includes a built-in {selectionMarkdown} tag that takes any text you’ve selected from the page and does some simple Markdown conversion of elements such as links, emphasis, strong and so on. Here’s an example:

Still, [as Marvin and Tammi say](https://www.youtube.com/watch?v=svAs-6MiqxE&feature=kp), ain't nothing like the real thing, baby.

I haven’t tested this extensively to see what breaks the encoding, but it meets my limited expectations.

There’s also a {selection} tag that just grabs the selected text. I use this, along with the title, URL and a blockquote prefix, for research notes with an attribution.

> {selection} From: [{title}]({url})

So I just select some text, invoke the Template action, then paste:

This works, but… blech. There’s a better way. From: Quicker Markdown linking with TextExpander - All this

There are some limitations here.

First, it requires Chrome. That’s fine for me, but you may prefer another browser. (I keep Firefox around just for those moments when I need TableTools2, the Firefox extension that Sorts, Searches, Summarizes, Filters, Copies, Charts, Rearranges, Combines and Compares HTML Tables!)

Second, it requires going to the browser tab I want to copy from, which is a context switch specifically avoided by Dr. Drang’s script. I find this an acceptable compromise — generally I’m already looking at the tab when I want to grab a link or other data from it, then switching over to the editor in which I want to use the results. Your mileage may vary.

I’ve used all of, what… four of the built-in tags here, and none of the available operators. There’s just a ton of potential in Template. It’s in no way a replacement for TextExpander, but it is another incredibly handy arrow in the quiver.

And now that I think about it, some pretty interesting things could be done with Template and TextExpander together to extract elements of a page, place them on the clipboard, then paste them with additional formatting or cursor placement via a snippet and some script. Hmmm....

Teaching Programming with Human Functions

Today, in my RubyStory class, I attempted to introduce the kids to Ruby functions. I won’t go so far as to say it was a disaster, but it didn’t go particularly well. They just didn’t get it.

OK. Functions are a pretty big concept for a new programmer to grasp.

I also made a major mistake: too much talking, not enough coding. The kids are much happier and seem to understand better when actually writing code, making things happen and experimenting on their own.

I did experiment with a different kind of example, however, and it seemed to bring some fun and understanding: “human functions.” Basically, the kids became functions and we interactively ran the program by talking to each other. Here’s how it worked.

First, I took one of the students, Sophie, aside and gave her some secret instructions: “Take the word you’re given and use it in a sentence.”

Then, one of the other students would “call” her with a word: “Sophie: donuts.” Sophie would respond “I love to eat donuts.”

We had some fun with it, as 10 year old kids will, and changed up the examples a bit. As I explained, this pretty much equates to the following code.

def sophie(word)
    puts "I love to eat " + word
end

sophie("donuts")

This seemed to help the kids understand a lot better. I think next class we’ll start out with more exercises like this before moving to the code. We could get multiple human functions involved to demonstrate how functions generalize tasks within a program.

For example, here’s a simplified version of our storytelling program.

def prompt(choice1, choice2)
    print "Which do you choose (%s or %s): " % [choice_1, choice_2]
    answer = gets.chomp
    return answer
end

def story
    puts "A zombie appears. Do you run or fight?"
    action = prompt("run", "fight")

    if action == "run"
        puts "Chicken! Bawk bawk bawk!"
    elsif action == "fight"
        winorlose
    end
end

def winorlose
    puts "Rolling the dice..."
    diceroll = 1 + rand(6)

    if diceroll > 3
        puts "Yay! You win!"
    else
        puts "Sorry, you lose."
    end
end

My human functions can run this program.

  1. Kendall starts the story, and passes the the prompt to Arden.
  2. Arden asks Teddy the question and returns his answer to Kendall.
  3. Kendall either ends the story (“run”) or calls Sophie (“fight”).
  4. Sophie rolls a die and, depending on the roll, tells Teddy whether he won or lost.

We’ll have to see how it works. Looks like I’ve got a bit of writing and scheming to do before the next lesson.

Teaching Kids Programming With RubyStory

TL;DR version: I wrote some course materials and sample code for teaching the basics of Ruby programming to middle-school kids. The course is called RubyStory and teaches just enough Ruby to create a choose-your-own-adventure style storytelling game.

RubyStory


Last year my older daughter started fifth grade and brought home a school-supplied MacBook. Which is great. I think it’s important to give kids a chance at an early head start to develop technology and programming skills — an early taste, anyway, to see if they like it — particularly the girls.

I set about looking for an appropriate learning resource to teach my daughter. There’s a lot out there. Unfortunately, none of it quite appealed to my preferences.

I wanted something easy for me to read, parse out what was being taught, and know what to pass on to students. Many of the course materials I reviewed required a lot of up-front reading, then I’d have to create my own teaching notes.

Adults and older children might be motivated to learn programming for its own sake, but I think younger kids (8-13 at least) don’t have the same motivation (exceptions discussed below).

Learning while doing something fun, however, seems to work. So I wanted to start with an interesting goal and make sure each step along the way was both educational and fun.

Finally, the laptops at my daughter’s school are locked down, so I needed something that required no software not already installed on the machines.

Ultimately, it seemed easier to create my own materials. As a bonus, as mentioned in my posts about writing about code, I’d probably learn a lot in the process. And I did.

RubyStory

The result is a course I wrote called RubyStory and you can grab all of the materials from Github. The details are covered in the readme.

The course materials are intended for teaching to kids. I suppose they could be used for self-instruction, but my assumption is that kids who are ready and motivated to learn programming on their own are probably also ready and motivated enough to learn from a book or a more traditional tutorial.

I recommend Zed Shaw’s Learn Python The Hard Way and Rob Sobers’ Learn Ruby The Hard Way. Both influenced the storytelling aspect of RubyStory.

The RubyStory materials are intentionally sparse. There’s an outline and sample code and handouts. There’s a slide deck, but it’s mostly just to show the code examples, which students can then type on their own.

The outline provides a concise overview of the topics to teach, but be prepared to fill in details, answer questions and riff a bit as your students require.

I wrote this course with the assumption that the teacher already has some basic programming knowledge. You don’t need much:

  • Creating and using variables
  • Strings and integers
  • Basic math and Boolean logic
  • Printing messages to the terminal
  • Capturing input from the command line
  • If statements
  • Functions

That’s all we use. Even if you know nothing about Ruby, you should be able to pick it up quickly. (I knew almost nothing about Ruby before starting this project.)

Why Ruby?

As you can tell from the minimal set of programming concepts covered by RubyStory, it’s hardly language specific nor does it really “teach Ruby.” In this case, Ruby is a convenient tool.

First, Ruby is already installed on every recent MacBook. The version installed is not important.

We don’t need any special tools to program with Ruby, just Terminal and a text editor. TextEdit isn’t the tool I’d prefer — syntax coloring would be a nice feature — but we can live with it for simplicity. (The slides do include syntax highlighting.)

Ruby has very simple syntax and very little necessary punctuation. Whitespace and semicolons aren’t that important and there are very few parentheses and brackets to worry about. I’ve found that kids have enough trouble with accurate typing. Simple syntax makes troubleshooting much easier.

Plus, I wanted to learn some Ruby. And I did.

Next Steps

Please fork the RubyStory repo and give teaching a try. I am continually updating the materials as I teach and learn from the kids — what the enjoy, what they build, what questions they ask, where I can help them go next. Let me know what you learn while teaching with RubyStory.

As written, RubyStory should be easily adapted to Linux systems, but I haven’t yet into what additional material would be needed for Chromebooks or Windows. It’s on my to do list.

Other than that, I’m now focused on using RubyStory for teaching in my community. I hope you will, too.

Beginner iOS Developer Resources

I’ve been learning the basics of iOS programming for the past few months. The best resources I’ve found to get started are tutorials — working through the app project and then making my own customizations to further extend my understanding.

Last week I built my first app entirely of my own devising. It’s a trivially simple GPS-based app and the details aren’t worth sharing (not yet, anyway).

However, there were a number of hurdles along the way. I thought it would be helpful to share some of the useful resources that helped me get over those hurdles.

First, two books that I highly recommend for learning iOS and Xcode are IOS Programming: The Big Nerd Ranch Guide by Joe Conway and Aaron Hillegass (make sure you get the most recent edition) and the Your First iOS 7 App ebook by Ash Furrow. Ash went above and beyond by helping me with a few questions as I worked through his book.

I’m dealing with CLLocationManager, and the locationManager:didUpdateLocations method changed with iOS 6. Matthew at DevFright.com has written some good posts on this including a DidUpdateLocations iOS Example and A Closer Look at the CLLocationManagerDelegate that may help you understand better how to deal with location data.

Daniel Isenhower has a good post explaining Using CoreLocation (GPS) on iOS to track a user’s distance and speed. He’s really explaining his own PSLocationManager library, but I found getting a grasp on how he built PSLocationManager to be a good tutorial in the underlying CoreLocation framework.

A polished app needs icons and launch images. The details on the sizes you’ll need are in Apple’s iOS Human Interface Guidelines: Icon and Image Sizes.

Speaking of icons, Mandar Apte created a handy iOS 7 Icon Template for Pixelmator.

Status bar display details changed in iOS 7 and, because my app has a black background and does not employ a UINavigationController, I had a hard time figuring out why the status bar wouldn’t appear. (It was there, but it was black. Not helpful.)

Taylor Case wrote an in-depth Developer’s Guide to the iOS 7 Status Bar that explains the status bar changes and what you can do about it. Related reference material: Apple’s iOS Information Property List Key Reference.

Something I never did find: a good, current, step-by-step guide for updating developer certificates and provisioning profiles. I muddled through and seem to have pressed all the right buttons in the right order — at least well enough to get the app on my test device — but it was more accident than expertise. Let me know if you come across a useful reference.

Writing About Code: Structure

In my previous post, I provided some tips about how to get started writing. That’s all well and good, but you would probably also appreciate some tips on what to write and how to organize your writing into something coherent and readable. Let’s dig into that now.

Many of us were taught a five-paragraph mode of construction: tell us what you’re going to tell us, tell us, then tell us what you told us. This is boring, repetitive, and evil. Don’t do it.

Instead, consider this structure for your writing:

  1. Problem
  2. Solution
  3. Next steps

It’s similar to the old five-paragraph model — there’s an introduction, a body and a conclusion — but I think this structure better directs the organization of your writing and makes for more interesting reading.

The problem statement

The problem statement is the introduction. It serves two purposes. First, it explains briefly what your article is about. Second, it’s your opportunity to grab the reader’s attention.

Starting with the second point, many readers think being outrageous or funny makes for a good hook. While that can work, it throws an unnecessary variable into the equation. Are you really funny? Is that enough to hook a reader? Are you sure?

Maybe it’s better to just clearly state what you’re writing about. Provide some context: what does it relate to (language, platform, type of development…), and why should I care (am I doing it wrong, does this make my code faster, stronger, less buggy…)? This is why I called it a “problem statement.”

Readers are often more interested when you clearly define your subject within a the scope of a problem they might encounter and one or more solutions that solve the problem. One approach, of course, is to literally solve a problem, but taking a more abstract view of the problem-solution structure can help guide your writing on other topics as well.

Keep your introduction brief, but it can be several paragraphs if necessary to set up the context in sufficient detail. However, make sure at least one paragraph — preferably the first or last paragraph of your introduction — clearly states what your entire post is about. People who will share your article in social media, aggregators, and newsletters will cut and paste. Make it easy for them.

Here’s a good example of a brief and to-the-point introduction in an article by Chris Eidhof on Lighter View Controllers.

View controllers are often the biggest files in iOS projects, and they often contain way more code than necessary. Almost always, view controllers are the least reusable part of the code. We will look at techniques to slim down your view controllers, make code reusable, and move code to more appropriate places.

Notice that, in three sentences, Chris explains the context (view controllers in iOS programming), the problem (they’re too big and not reusable) and what he’s going to explain (a solution for slimmer, more reusable view controllers).

Here’s a longer example from Charles Petzold’s DirectX Factor column in MSDN Magazine.

High school geometry comes in two distinct flavors: Euclidean geometry is oriented around constructions, theorems and proofs, while analytic geometry describes geometric figures numerically using points on a coordinate system, often called the Cartesian coordinate system in honor of the pioneer of analytic geometry, René Descartes…

In the previous installment of this column… I discussed how to use the ID2D1PathGeometry to render lines in a finger-painting application that runs under Windows 8. Now I’d like to step back and explore geometries in broader detail, and in particular investigate some of the intriguing methods defined by ID2D1Geometry for manipulating geometries to make different geometries.

This is a longer introduction, and I’ve even left out a paragraph for clarity, but you can see that it includes the same building blocks: a context (geometry in Windows 8 programming, continuing from a previous articles), a problem (geometry is hard, you need to know how it works), and a solution (learn about ID2D1Geometry).

If you can keep your introduction — your problem statement — focused like this, it will help you keep the rest of your article focused as well.

The solution

This is the meat of your article and where you’ll spend the most time writing. I won’t spend too much time on this as it’s really the focus of my first post on getting started writing. You just need to pick a subject and start writing.

The main portion of the article is where you can explain the problem or opportunity in more depth than a concise intro problem statement allows. Stop and provide some more context if necessary, though don’t let it distract from getting to the solution. If the problem starts to become the entire article, you might want to rethink what the article is about. Maybe that’s another writing project altogether, or maybe you can link to more context elsewhere.

How you write about your “solution” depends on subject and the way you want to organize your ideas. A few common patterns are:

  • Start from the beginning and work through to solving the problem
  • Pick a few key elements to explain
  • Top ten lists (pro tip: odd numbers work better)
  • Analysis of different patterns or implementation approaches
  • Pros and cons

There’s not necessarily a right or wrong way to organize the core of your writing. Go with your gut, pick something, and run with it. After you complete a draft, if the organizing theme you’ve selected doesn’t seem to be working, don’t try to force it. Rather, be open to refactoring and heading in a different direction. Reorganizing takes less effort than re-writing.

Next steps

I’m of the opinion that a blog post or article does not, in fact, require a formal conclusion. If you finish your subject and want to simply stop, that’s fine.

This is particularly true of very short blog posts that cover a single, very focused subject. Provide some context and a problem statement, explain yourself through your solution, and done!

If you do want to provide some closure, don’t simply restate your original thesis. Instead, you can just sum up quickly: “That’s a quick overview of recursive dohickies in action.”

Another approach, if there are other considerations, is to qualify your solution. Although I’ve warned against pedantic, edge-case addicted readers, you don’t need to be all-inclusive or all-encompassing in your solution. Just explain that there’s more to the subject: “This solution works well for most apps, but edge cases X, Y, and Z require additional hemming and hawing.” Maybe that’s fodder for future writing.

As implied by my heading, it’s always helpful to suggest some next steps for the reader: where to learn more or find additional examples. Other potential solutions or associated technologies. Ideas for further or more sophisticated implementations. You don’t need to go on at length. A simple mention and, perhaps, a link goes a long way.

Links are the lifeblood of the web, and links in your article are good. They let you pull related context and information into your post without having to write it. They also let you recommend quality sources of information and code to your readers, situating your own writing within the larger web of discussion on the subject.

You can (and should) link to your own previous posts. Go back and add links in previous posts if you cover the subject again later. This is particularly important for multi-part series of articles so a reader can find the beginning of the series from any post in the series, then follow through from the end of one post to the beginning of the next. If you make it easy for readers to stay on your site, they will.

Link to other people’s posts if they’re relevant and helpful. People (readers and writers) appreciate that, and if they’ve already covered a subject, it saves you from repeating it.

Link to apps, libraries, reference material and anything else that you use or discuss in depth so readers can find and use it too. Make sure you get the name right, though, and it’s a nice touch if you check occasionally that links still work.

Comments on the code examples

Code is great. You should definitely include code examples if they’re relevant to in your writing. But a code example does not replace an explanation.

If you show code, you should explain the code, even if it seems obvious to you. You wrote it. Of course it’s obvious. However, your reader is trying to learn. If it was obvious, they wouldn’t be reading… and many of your readers are going to be far less accomplished programmers than you. Help them understand.

In fact, this is where a lot of official documentation falls down. It shows the most basic example, but never take it farther than that. Then it jumps straight to a complete sample app. There’s often little explanation of how you get from A to Z.

And as we know, the API is rarely as straightforward to use as the author thinks. There are always inconsistencies and gotchas and misnamed features and things that look the same but do something completely different.

You don’t need to show all of your code if it’s available somewhere else. Just the important or interesting bits, and a link to peruse the rest.

If there are dependencies, make them clear.

Test your code in a fresh environment (VM maybe) to double-check that there are no unexpected dependencies. “It works on my machine… ” is never a good excuse.

The specific coding style choices you make are not as important as consistency and clarity. Pick something and keep with it. It can help to use super-clear naming that you might not use in real code.

More on writing about code

This is part of a series of posts discussing the main points of my “Writing About Code” presentation at Vermont Code Camp 2013. Here are all of the posts in the series:

Writing About Code: Getting Started

Writing About Code: Structure

Now, get writing…

Writing About Code: Getting Started

Writing code is job one for most software developers, but learning to write about code is almost as important. Whether you’re documenting an API or showing off your own smarts, when you set out to write about what you think you know, it tests how well you really know the subject. As you write, you’ll often end up deepening your understanding of how the code works and honing your skills as a developer.

In this post I’m going to provide some tips and tricks for programmers who haven’t done much writing that will help you get started and find early success that fuels more writing.

This is a distillation of the first part of my “Writing About Code” presentation at Vermont Code Camp 2013. I don’t believe dumping my slides on the web helps. Instead, I’m pulling the most important ideas from my presentation into a few blog posts that are easier to read, digest and use to fuel your own work.

Why write about code?

There are many reasons to write about code. Maybe you want to share your knowledge and enthusiasm for programming, to market a product or teach customers how to use it, to promote your own abilities or because it is (or should be) part your job.

But I’d like to suggest another, more valuable reason, best summed up in this ancient wisdom from Seneca the Younger: Docendo discimus (“by teaching, we learn”).

Whether you write for yourself or decide to write publicly, you’ll start to explain something and, often as not, start wondering: Really? Is that all there is to it? What am I missing? How does this work? Engineers — your target audience — are always going to point out edge cases and pedantic details. Are you ready?

Go ahead and second guess your assumptions about your code, dig into the how and the why. You will most likely learn something new and improve your skill as a developer.

My code speaks for itself, right?

Unfortunately, your code does not speak effectively for itself — not for a wide audience anyway.

A code example does not replace an explanation. Sure, there are times when sharing a simple code snippet seems sufficient, but even then it’s usually posted in the context of a discussion… usually via social media.

If you show code you should explain the code, even if it seems obvious to you. You wrote it, so of course it’s obvious. But there are many other people — your potential readers — who are trying to learn. If the concepts you present in your code were obvious, these people wouldn’t need to be reading about it.

Many of your readers are going to be far less accomplished programmers. Believe it or not, by simply taking the time to research and write a blog post, you become an expert. Help them understand.

In fact, this is where a lot of official documentation falls down. It shows the most basic example, but frequently fails to take it farther than that. Then it expects you to jump straight to a complete sample app. There’s often little explanation of how you get from A to Z.

You may think it’s all be written before. What do you have to contribute? We’re still figuring this programming thing out. Every bit of knowledge helps move the profession forward. People are still writing about C. People are still writing about Cobol! Your unique approach to the subject may be the key that unlocks a problem for some reader.

Fear of writing… or how I learned to stop worrying and just write

The most important tip: Write something. Anything. Just get it out of your head and on the screen. Make time to write every day. 100 words or 30 minutes or whatever seems achievable on a regular schedule. As you become more comfortable, try increasing your target time or word count.

Do make it a habit, but don’t make it a chore. If you get stuck, stop and come back to it later.

Use the tools and languages you use every day. Write about the thing on your mind right now. A distraction that often gets in the way of writing (and probably coding, too) is obsessing over the “best” tools. There is not best writing tool, and messing with different editors just keeps you from writing. Word is fine, but so is a basic text editor… your IDE will probably work fine if that’s where you’re most comfortable and productive.

Don’t underestimate the usefulness of pencil and paper.

A helpful approach for avoiding editorial paralysis is to commit yourself to at least two trips through the material. I think most people get in trouble by trying to edit while they write. The result is usually not writing. An outline or a list of the major points you want to touch on works well, but from that starting point, try to write stream-of-consciousness. Get as much down on paper as possible.

Don’t fixate on the entire article. Work idea by idea, section by section. Each sentence is a building block for a paragraph, and each paragraph is a building block for your article.

Although correct technical details are important, as are correct spelling and capitalization, don’t get hung up on researching each topic as you write. If there’s something I’m not sure about or that needs more detail, I prefer to make a note to myself inline to go back and double-check or add more information later. Better to have the sketched out skeleton of your writing in place rather than getting side-tracked by research from writing at all.

Write a complete first draft before making any edits or revisions. That includes fretting about spelling, grammar, and so on. Once that draft is complete, then read it through, fix mistakes, add details, re-order, refine, and refactor as needed.

Focusing your big ideas into byte-sized pieces

A common problem for writers is determining the scope of what you’re going to write about. If the idea is too big, you’re likely to run into two problems: You either never finish (which is frustrating) or you skip over important details to finish (which leads to a poor finished product).

At least when you’re starting out, focusing your writing on small, achievable goals will help you succeed more often, giving you confidence in your writing and setting up a positive feedback loop of writing, accomplishment and more writing.

It’s often better to focus in on a very specific detail and write about that as clearly as possible. You have a more clear goal for the writing in front of you. You can often think around the smaller concepts more easily. Plus, there’s less to write — you’ll finish more quickly.

You can stitch together other small, focused bits of writing into episodic blog posts (Oren Eini does this very effectively on his blog) or into a longer article.

You’ll often find that small topics aren’t really so small when you dig into them. Think about not just how you implement a solution, but how it works… and why. What are the edge cases? What’s helpful to know? How much is boilerplate, implemented for you by the IDE or framework? Can you explain how that all works? How much is “received wisdom” about how things should be done, or code IntelliSensed in with a keystroke?

In fact, I suggest, as an exercise to practice writing about your code: take a chunk of code and explain it block by block. I bet you’ll discover quite a few assumptions you’ve made along the way. It doesn’t have to be your code. Document some random source code just for the practice.

Avoid pasting in large code blocks. It hinders the flow of reading and distracts your reader while she deciphers the entire block. Instead, break your code into digestible snippets if at all possible. Explain each bit as you go through. At the end you can provide the entire code block for copying and pasting, or link to a file/repo.

I suggested digging into the details, but you don’t always have to explain how deep the rabbit-hole goes. Most of the time, unless you’re writing basic programming tutorials, you shouldn’t have to explain how a for loop works, or what you’re iterating or basics like that.

Instead, think about the conceptual building blocks of your idea. Break code down into snippets that let you discuss it in terms of those building blocks. For nuts and bolts coding, that may mean discussing code line by line within individual methods. Other times you might discuss the overall construction of an entire class (suitably simplified, if possible) or of classes within an application.

As an example, take a look at Chris Eidhof’s Lighter View Controllers article at objc.io, which examines code organization at the class and file level. Then consider Peteris Krumins’ Bash One-Liners Explained series of posts, which by definition examines one line of code at a time in great detail.

What to write about?

Still not sure where to start? Here are a few ideas:

  • Write about what you’re enthusiastic about
  • Write about what you’re curious about
  • Write about what you’ve done that makes you feel smart
  • Write about a problem you had to solve
  • Write about what annoys you or makes you smile
  • Write about what you don’t understand: you’ll learn along the way

There is a audience out there eager to learn. Start writing for them. It will do you some good, too.

People love to learn how things work… and why.

People love when someone else solves their problems.

People want to know what they need to know and where to find it. They want to know how to get started, and then they need to be handheld from the simple to the more complex.

People always appreciate clever and useful utilities and code snippets, and tips for how to use them.

Stop reading, start writing

You have some basic tools for getting started. Now put them to work and get started writing something every day. You don’t have to publish it. Just keep a journal for practice… a journal of ideas, which you might return to later for material as you become more confident in your writing.

This is part of a series of posts discussing the main points of my “Writing About Code” presentation at Vermont Code Camp 2013. Here are all of the posts in the series:

Writing About Code: Getting Started

Writing About Code: Structure

Now, get writing…

Making a Good Cup of Coffee

Coffee

A warm cup of coffee seems a universal morning ritual. Bad coffee seems pretty universal as well. But it’s not difficult to make a good cup of coffee. It just takes the right ingredients, a repeatable technique and a little trial and error.

Here are some tips for making a better cup of coffee.

Many people focus on brewing method - tools over technique - but no matter which method you have at hand, materials and preparation are most important.

To make a great cup of coffee you’ll need:

  1. Freshly roasted beans.
  2. An adjustable burr grinder.

I can’t overemphasis how important freshly roasted beans are to quality coffee. Some people say the first week or so after roasting are the best. More than a month is too old. If you buy directly from the roaster, they should be able to tell you when it was roasted. Many roast to order. If there’s no roast date on the bag, assume the worst.

Grinders are available in many sizes and prices, from $50 hand grinders to giant commercial electric grinders costing hundreds of dollars. The most important feature is the ability to adjust grind in small increments. I use a Kyocera CM-45 hand grinder and a Lelit PL-53 stepless burr grinder. The Kyocera is getting hard to find, but I’ve heard good things about Porlex hand grinders. In electric burr grinders, the Baratza lineup has something at a variety of price points and they have a good reputation as well.

On to preparation…

I prefer espresso, but for simplicity we’ll walk through brewing a simple single-serving of drip-brew coffee. This uses a “pour-over” filter holder like those made by Melitta, for example (here are some other options from Sweet Maria’s), and paper filters.

First, put approximately 4 tablespoons of the beans in your grinder. The actual amount isn’t as important as being consistent in how much you use. Grind the beans.

Put a filter in your filter holder and heat up the water to not-quite-boiling. Put the grounds in your filter and pour in two cups of water. Again, precision is not important, but you don’t want to overfill your coffee cup and you do want to keep the beans-to-water ratio consistent from cup to cup. Let the water brew through the grounds.

Here’s the important part to making a great cup: Taste the coffee. Prep it with milk and sugar if you like, but taste it.

Does it taste good? Fine, you’re done. Do the same exact process next time.

Does it taste watery and thin? Tighten the grind setting on your grinder slightly to make finer grounds. Do everything else the same.

Does it taste bitter, or did the water fail to brew through the coffee after a minute or so? Loosen the grind setting slightly to make more coarse grounds. Do everything else the same.

Brew another cup. Better? You can keep making small changes to your grind settings toward a more coarse or find grind until you get a great cup.

The trick here is controlling for all but one variable: grind. If you change beans, you may have to fine-tune your grind again.

Other brewing methods offer additional variable to tweak, from Aeropress or French Press steeping time to espresso machine pressure and temperature settings. You can imagine, however, that it’s easy to get out in the weeds with too many settings. No matter which method I use, I always go back to the basics: fresh beans, hot water, and adjusting the grind until the cup is tasty.

These days I get my beans from Barrington Coffee Roasters and Lucy Jo’s, who sell directly at my local farmer’s market. I also recommend Counter Culture Coffee who not only sell great beans, but are also leading the charge for direct, sustainable relationships with coffee growers around the world. In NYC you should give Cafe Grumpy a try. Wherever you are, find and support your local roasters.

Storing Art Safely

Earlier today I had a brief Twitter conversation with John Resig about storing art, specifically prints. I thought I’d share a few additional thoughts that didn’t quite fit into the space of 140 characters.

Disclaimer: I’m no conservation expert and my art isn’t particularly valuable. If in doubt, consult a pro.

The best method, I think, is to have your prints archivally framed and hanging on the wall. You can enjoy them and they’re relatively safe from damage. Unfortunately, framing is expensive and we only have so much wall space.

Although it’s common practice to ship prints in tubes, you should store them flat if at all possible. It’s almost always possible to flatten out a print, but in my experience the paper tends to develop a memory. The longer it’s rolled, the harder it is to flatten out without developing waves or ripples.

Flat Files

The obvious storage solution is a flat file cabinet. They make it very easy to simply lay the prints in the cabinet and be done with it. However, flat files are big, bulky furniture. The biggest commonly available size is 36” x 48”, which is a lot of real estate in your room. And remember, that’s the outside dimension — the largest print you can accommodate will be more than an inch smaller.

Flat files are also fairly expensive, though careful shopping on Craigslist or the like may turn up something useful.

All that said, if you can swing a flat file, it’s the way to go for safe, bulk print storage. I love mine.

Within the cabinet, some folks like to store prints in mylar sleeves. I tried this route and found the hassle and cost outweighed the utility: the sleeves don’t always lie entirely flat and I couldn’t stack prints without inducing some waviness in prints on lighter-weight paper.

I ended up taking the prints out of the sleeves and instead simply place prints on top of each other, alternating with sheets of acid-free blank paper.

Portfolios

For prints up to 24” x 36”, art portfolios with slip-in sleeves work great for storage. The stiff covers provide good protection for your prints, but make it easy to page through and admire your collection. They also can slip under a bed or, if you’re careful, lean against the back of a closet. Watch out for pests and spills, though.

I like the Itoya 18” x 24” Profolio and Profolio Evolution. This is a common size for gigposters, so the vast majority of my collection fits in these easily.

There are bigger portfolio cases. I have a 24” x 36” Stein deSign Picturesque Presentation Case. Pricey, and only comes with 5 sleeves, though you can expand up to 20 sleeves with “refills”. On the other hand, it’s a very sturdy alternative to a flat file for storing larger prints.

You may also be able to find fold-over artist portfolios in even bigger sizes. They don’t typically have sleeves to help organize your prints or hold them in place, so you need to be careful about handling. Look for acid-free materials.

DIY

I have a few really long prints that don’t fit in any of the commercially available, affordable solutions. So I made my own folders — basically a variation on the fold-over portfolio.

Get some 40” x 60” acid-free foam core boards and some acid-free hinging tape used for framing.

Put two boards on top of each other and tape one edge together, creating a hinge.

Carefully place the prints between the two boards. For added peace of mind, you might want to temporarily mount the prints on heavy acid-free backing paper using framer photo corners or clear mounting strips.

Hold the entire thing closed with big-ass rubber bands or similar. Handle the whole thing carefully — contents are likely to shift.

Get Your Own Art

Hand-made prints — screen prints, woodblock prints and lithographs, usually — are a great introduction to the world of art collecting. There’s something everyone. I really like Andy Warhol’s Cow Wallpaper, but that’s not going on my wall any time soon.

Instead, I accidentally fell into the rock art gig poster scene. You can learn more about it at gigposters.com and Expresso Beans, two of the more active communities for artists and collectors.

John, by the way, has his own fascinating site cataloging Japanese “Ukiyo-e” woodblock prints.

Full disclosure: some of the links on this page are Amazon affiliate links and I could receive a payment from them for any purchases you make during a shopping session initiated via these links.

Playhouse Product Testing

We had some friends and their children over for Christmas/Hanukkah dinner, and the playhouses I wrote about last week got some serious product testing.

There were seven adults in the house trying to have some grown-up conversation, and six kids — 1, 3, 4, 5 and two at 8 years old — simultaneously climbing into, out of and around the playhouses.

Total damage:

Eventually the red door came off the cottage, and some wrestling between three of the boys tore part of the lower-front corner of the cottage. Fixed it with some packing tape this morning.

I think some of the parents were appalled by what their kids were doing and I had to repeatedly tell them it was all in good fun. I wanted the kids to do their worst so I could see where the playhouses failed. We were all amazed that they provided as much fun and held together as well as they did.

Best playtesting ever.

View all of the posts in the archive, browse the tags, or subscribe to the feed for All Posts. You can also subscribe to a feed of just the posts tagged with tutorial.