Terrence Dorsey

Writer. Editor. Nerd.

Toolbox: Documenting Web APIs

My September column at Visual Studio Magazine covers Web API Documentation Tools — some tools and frameworks that make getting from your web service codebase to useful API documentation relatively painless.

I know documentation is not a favorite task for many developers, but it's really crucial for acceptance and ease of use for your customers. You don't have to write the Great American Novel, and these tools do most of the heavy lifting for you.

#

Toolbox: Semantic Highlighting

My August column at Visual Studio Magazine covers a recent obsession: Semantic Code Highlighting. You'll get a brief history of syntax highlighting, along with some examples of various kinds of code coloring, then I dive into some new tools that let you employ semantic highlighting in your own coding environment. I highly recommend it.

#

My Web Perf Book For O'Reilly

Head over to HTTP Archive and check out their trends graphs. Notice anything? That's right, web pages keep getting bigger and more complicated. The problem here is that — particularly in e-commmerce — consumers of your site expect it to load and become interactive quickly.

Turns out, the problems involved and solutions needed to fix them depend, mostly, on straightforward, Web Dev 101-level knowledge and technology. I recently wrote a short e-book on the subject for O'Reilly, Web Page Size, Speed, and Performance (free, registration required). There's also an accompanying blog post on O'Reilly Radar, It's time for a web page diet.

Slimming down web sites is not necessarily a matter of learning new and sophisticated programming techniques. Rather, getting back to basics and focusing on correct implementation of web development essentials — HTML, CSS and JavaScript — may be all it takes to make sure your own web sites are slim, speedy and responsive.

Interesting side note: mobile web users (and probably app users as well) expect faster interaction than on the desktop and are more likely to ditch an action if it's slow. Think about the implications of that complication on your app development plans.

#

Toolbox: HTTP Debugging Tools

In my July column for Visual Studio Magazine, HTTP Debugging Tools: Buy, Borrow or Build Your Own Tools?, I take a look at some of the popular current offerings: Wireshark, Fiddler, Charles and HttpWatch. Each represents a slightly different set of features at various price points, from free to enterprise subscription.

I also had a chance to talk with Eric Lawrence and Karl von Randow, developers of Fiddler and Charles, respectively, about the experience of building these apps.

#

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....

#

Toolbox: Code Editing and Collaboration Tools

My May column is up at Visual Studio Magazine, 25+ Tools for Cross-Platform Code Editing and Collaboration. I take a look at code editing and collaboration software that offer a familiar environment across multiple operating systems. Most are browser-based coding tools, and I was surprised how polished and sophisticated these tools have become.

Lots of fiddles. Lots and lots of fiddles.

#

New VSMag Columns: Nuget, Git and Mercurial

Somehow in all the recent excitement I missed the publication of my March and April columns over at Visual Studio Magazine.

6 Top .NET Package- and Dependency-Management Tools in March covered some background on why package management tools are great and a quick overview of some popular tools for Windows. Nuget, obviously, gets most of the attention, but I also highlighted OpenWrap, NPanday, Chocolatey NuGet, Chewie and Ninite.

To be perfectly honest, I think these tools all need work to catch up with the likes of apt-get, homebrew, and the like on Linux and Mac. However, I can't imagine life without package managers and applaud any effort to refine tools like this on Windows.

Source Code Control with Git and Mercurial in April covered resources for using the popular distributed source code control and collaboration tools Git and Mercurial on Windows. Many of these links come from my own "how do you do that again?" archive because, well, I regularly forget how to do much beyond cloning, adding, committing and pushing. Merge conflicts? Oh my...

#

Toolbox - An Update on Windows Azure Tools

My February column is up over at Visual Studio Magazine and it includes 43 Great Windows Azure Development Resources . I hope you find it helpful.

A lot has happened since I wrote my first Windows Azure Development Resources column for MSDN Magazine back in 2010. The Azure team is doing great work and they should be proud.

#

Updating the Reading List

Quick note to mention that I'm updating my Reading List page from using Amazon affiliate links to instead linking up reviews or other relevant discussion.

Two reasons for this:

First, I'm a proponent of supporting local, independent booksellers and I feel that directing readers to Amazon undermines that.

Second, the Amazon links were a convenient way to direct readers to book summaries and reviews. The affiliate links were a "bonus," but one that never actually paid off. So why bother? There are other sources of more useful reviews. (For example, check out the 1937 review of The Hobbit by C.S. Lewis!)

Replacing older links will be an ongoing project, so check back in occasionally for new book recommendations as well as new review links.

Happy reading!

#

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.

#

More articles...