Alex R. Young

Researching for Technical Writing

2012-05-25T01:05:00Z

How are technical articles and books written? It all comes down to research. Every editor I've worked for has always extolled the importance of research, and a well-researched article is certainly more pleasant to write.

The following suggestions are based on the methods I employ intuitively, so I may have missed out some important points. However, I hope it gives readers some ideas on how they can bolster their own technical writing efforts.

Reader Competency

First, decide who your article is for, and what they already know. Writing for beginners means drawing on standard documentation, and perhaps putting more creative effort into example code.

Writing for more advanced developers requires more work. When targeting readers at this level a huge amount of effort should go into understanding deeper issues. For example, rather than researching core libraries, I'll research more involved problems such as structuring or scaling large applications.

Community

The community around a given technology generates a wealth of research material. Try reading mailing lists, blogs, social networks, and Hacker News/Reddit comments. This really helps show what areas commonly confuse people.

When researching Windows and Node: Portability, I found several relevant posts to the nodejs Google Group by prominent developers in that community.

Issues

GitHub and similar services provide issue tracking. Bug reports and feature requests give amazing insights into the problems users have.

It can even be productive to see how the authors fixed bugs, because it might demonstrate an interesting technique or a weakness of the underlying technologies.

Related Projects

Don't just look at the core technology that you're covering, but also read about prominent related technologies.

If I wanted to write a book about Ruby, I wouldn't just research Ruby and its core libraries, I'd also focus on its major open source projects. Researching the Rails community would give big clues as to how people perceive and use Ruby itself.

Source

Finally, any time spent looking at the technology in question's source code is time well spent.

When I write about Node, I always have an editor open with Node's source code in it. This helps me expand on material in the standard documentation, and also learn techniques straight from the developers who made the technology I'm writing about.

Saint Spectrum Day

2012-04-23T01:04:00Z

Image from: wallpapers for World of Spectrum

I've been working as a programmer for 11 years now, and it's partly due to the ZX Spectrum 48K that my dad got me at some point in the 80s. I wanted to learn to program it, and the fact it booted straight into BASIC encouraged a lot of experimentation.

Computers don't work like that anymore, but some people want them to.

People find it surprising that there was an influential British computer, but the truth is there were many computers that had limited releases in their native territories; some of them used fascinating Russian Zilog Z80 clones and were compatible with Sinclair's machine.

Looking back, it's easy to think that the 80s saw a more diverse era in terms of home computer hardware. However, if you consider that the Z80 was actually an improved implementation of Intel's 8080, and was used in everything from the Game Boy to the Amstrad CPC, then it's debatable whether things have really changed in terms of hardware diversity.

The biggest change in computing since the era of the Spectrum is societal -- we decided to start connecting our computers together on a global scale, and putting connected devices in our pockets. Now computers really are a canvas for unrestricted creativity.

usevim: For hjkl Wizards

2012-04-02T01:04:00Z

Usevim is my new blog all about Vim. You can follow it on the usual social networks:

Twitter: @vimnews
Facebook: vimnews
Google+: usevim
Feed: usevim

I've been collecting interesting Vim-related links for years, and I've wanted to launch a Vim blog for a long time.

The format is similar to DailyJS -- weekly plugin roundups and lots of original content. I'm currently publishing every Monday, Wednesday, and Friday.

If you've got Vim plugins or tips to share, or would like to write a guest post, get in touch.

The Key to Android Domination

2012-03-20T00:03:00Z

Where's Google's Android IDE? They have good Eclipse support which goes some way to competing with Apple's Xcode, but the experience of developing with Xcode is far more focused and arguably better.

I don't actually think developing a native Windows, Linux, and Mac OS IDE really fits with Google's approach -- they'd rather give developers the platform then get out of the way by allowing us to use our own tools. However, there's one huge pain point in iOS development that Google could attack to win over developers: the difficulty of getting your code running on your device.

The Developer's Experience

After downloading several gigabytes, then setting up the necessary certificates, a developer can finally run their first Hello World application on an iOS device. This represents a weakness in Apple's approach that could be exploited.

How? Well, given that it's unlikely that Google will release a cross-platform IDE themselves, how about creating a web-based IDE? That might sound like a nightmare to Vim hackers like me, but hear me out. Imagine if Google had a developer site that ran something as high quality as Cloud9 IDE (which has Vim shortcuts), with a built-in Android simulator.

Within minutes developers could run a simple application in the simulator, without even owning a device. No gigabyte downloads, no confusing certificates. Google's web-based market can trigger downloads on Android devices, so how about linking devices with the IDE so apps can be sent directly to a device to run it? A new Android developer with little experience could have a real app that they've made running on a device in minutes.

This also makes a huge amount of sense given ChromeOS and Chromebooks.

Remove the Barriers

That's what Apple and Google's goal for developers should be: to let people run code with as few barriers as possible. I think a robust web-based IDE would play a huge part in this, and the first to deploy it will get a huge win in terms of developer support.

A vim-friendly Mac Keyboard

2012-01-15T00:01:00Z

I suspect the ultimate vim keyboard is the Happy Hacking Professional 2. The Control key placement is good for vim, tmux, and screen, and the removal of uncessary arrow and function keys appeals to me. However, it's $300, so I wondered if it's possible to hack the keyboard I already own into being a little bit more vim-friendly.

Swapping Modifier Keys

On a standard Apple keyboard the position of Control sucks. Fortunately, Apple gives us the ability to swap modifier keys around with no hacking at all.

Under System Preferences, Keyboard, Modifier Keys..., the Control and Caps Lock keys can be switched:

It only took me a few days to get used to this, and it works well for those of us who type Control a million times more often than Caps Lock.

Use hjkl Instead of Arrows

KeyRemap4Macbook allows any key to be remapped, and key repeats to be accelerated. Of interest to us is the 'Vi mode' setting list, and 'Ubiquitous Vim Bindings'. I selected 'Fn+hjkl to Left/Down/Up/Right' so I can use hjkl to move the cursor in any application.

KeyRemap4Macbook requires a reboot after installation, but once it's running the settings can be changed and experimented with at any time.

Using Powerline with Mac OS

2012-01-13T00:01:00Z

vim-powerline by Kim Silkebækken is a great plugin, but it's a little bit tricky to get it looking right in Mac OS. I've tested it in both Snow Leopard and Lion and figured out how to get it working nicely.

Snow Leopard's Terminal application doesn't support 256 colours, so I started using iTerm2 instead. With a little bit of configuration it's functionality equivalent to Terminal, and offers tonnes of extras. Lion's Terminal is fine. Both need to report xterm-256color, so ensure this is set up in the Preferences pane. To get the cool UTF-8 fonts you'll need patched fonts. Nick Quaranto posted some suitable fonts here: vim-powerline patched fonts. I like "Menlo" myself.

Next, read the Powerline documentation. When the author says set nocompatible and set laststatus=2 are required he means it, so add those to ~/.vimrc. I also had to add set t_Co=256 and let g:Powerline_symbols = 'unicode' (Kim notes that setting it to fancy will work as well, and make better use of the patched fonts).

Changing Powerline_symbols requires the cache to be cleared, so rm /tmp/Powerline.cache.

Now your vim should look like Kim's screenshots in the Powerline repository.

Build an IDE with tmux and vim

2011-12-19T00:12:00Z

A friend of mine had visited an office where the employees used tmux and vim to edit Ruby projects. He wanted to know why people would work with the console version of vim, considering the loss of the convenience of mouse input.

I actually find this a good way to work, for several reasons. Originally, using console vim forced me to learn vim's motion commands properly. Combined with touch typing, this opened up a range of powerful ways to jump around files and lines arguably more efficiently than by using a mouse.

I like to tile terminals alongside my editor. My web development work usually requires a console for issuing ad-hoc commands, a database console, and a log viewer. Some of my projects have test suites that run automatically when files change, so I like to be able to see the status of my tests as well.

There are vim plugins that provide integration with these things, but I feel more comfortable with the vim/tmux combination. I think it's a visualisation thing.

By using command-line tools this way, we're effectively building a customised, lightweight IDE. I also find the idea of using Unix commands in my spare tmux console panes appealing, because it's easy to pipe commands together thereby performing complex scriptable operations without the bloat of an IDE.

The difference between this approach and a traditional IDE is this interface adapts around my current task, and is only limited by the thousands of commands and scripting languages that I have installed. Rather than creating a template of some kind, I create tmux panes and vim split windows as required. Despite Eclipse and Xcode offering task-focused interfaces, I still feel like they get in the way too much. Particularly in Xcode, where keyboard shortcuts feel like an afterthought, and my hand is consistently on the mouse.

Task switching is another benefit. I'm a freelancer, so in a typical working day I may switch between three or four projects. By using tmux, I can detach from a session and come back later, keeping me focused on the current task at hand. I think this is really an advantage of console vim over GUI vim and a collection of terminals, because Eclipse and Xcode attempt to save interface state when closing a project (although the latest Xcode seems to close my split panes all the time).

Why People Use `hjkl`

It may seem needlessly awkward or elitist to some, but if you can touch type relatively correctly, vim and tmux (set to using vim's keys) make it easier to keep fingers on home row and off the mouse.

That's the secret of hjkl -- people who like it generally touch type correctly. For those unaccustomed to these keys, try taking it slowly for a few days. Type deliberately and methodically, making full use of the little fingers.

The hjkl argument reminds me of trying to convince novice PC gamers to learn wasd over the arrow keys. At first wasd feels less intuitive, but it makes using the keyboard and mouse together a lot easier. The advantage becomes apparent when actually trying the alternative in earnest.

Configuration Tips

I use this in my .tmux.conf:

set-window-option -g mode-keys vi
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

This allows me to move around tmux using vim's movement keys.

If you're struggling to get used to vim's movement keys, try disabling arrow keys for insert mode: Vim: Making those Arrow Keys Work With You.

If you're new to vim, it's also worth remembering that it supports ctags. The TagHighlight plugin can dynamically display a panel of tags in a pane for the current buffer. This is yet another IDE-like feature.

Dotfiles

Does your IDE's configuration sync between multiple computers?

I have a private git repository called dotfiles that has my vim and ctags configuration and plugins. I wrote a little install script to automatically symbolically link configuration files with the files in my local dotfiles repository. When I get a new computer, one of the first things I do is to check out this repository. When I start editing a project, vim and tmux behave exactly as expected.

Copy and Paste

I usually copy and paste console output into vim by using tmux's copy and paste commands. Depending on how tmux is configured, the exact keyboard shortcuts may vary, so it's worth reading man tmux about how this works. The default should be ctrl-b [ to enter copy mode, Space to start making a selection, Enter to copy the selection, then ctrl-b ] to paste.

Motion Commands

To really get efficient with vim, try to always question when a keyboard-heavy operation could have been better served by using the appropriate motion commands. For example, when I first saw ~ (swap case) I thought "that's cute, I'm never going to use that". I've actually used it three times while editing this post.

I started to get the hang of motion commands when I noticed more experienced vim users avoid going into insert mode unless necessary. Keep coming back to vim's help, and you'll be surprised how many ways there are to improve your editing skills.

iOS 5 Redemption: ARC, UIAppearance, Blocks

2011-12-07T00:12:00Z

iOS 5 redeems iOS development in my eyes through several new features. There are Objective-C changes, but also new APIs that make common tasks a lot easier. When Apple released the new SDK, I created a blank project to see what fundamental project organisation changes had been made, and the only major thing I noticed was the addition of Storyboards.

Unfortunately, Storyboards are not compatible with iOS 4. It may be possible to create a fork of a project with iOS 4 support that has a different UI, or to somehow conditionally use Storyboards. However, we all know how much hand-coded interface development is required for real iOS projects, so I can't see myself using Storyboards.

Automatic Reference Counting

Automatic Reference Counting implements automatic memory management for Objective-C objects and blocks, freeing the programmer from the need explicitly insert retains and releases. It does not provide a cycle collector; users must explicitly manage lifetime instead.

From: LLVM: Automatic Reference Counting

When friends tell me they're learning iOS development, the first thing I find myself helping them with is memory management. Learning where to use retain, release, and autorelease isn't too difficult, but it's sometimes hard for people to realise it's a convention rather than something the compiler will automatically help with. That has now all changed with Automatic Reference Counting (ARC).

ARC is a build setting, and once it's enabled properties get new keywords and the compiler will raise errors where the old memory management keywords are used unexpectedly. Now we can alloc and initialize objects without worrying about releasing them. If you work with pure Objective-C (no C data structures) then this is easy and cuts down a lot of code. It feels wrong at first, but after a while it's completely natural.

Be sure to study the notes in What's New In Mac OS X: Automatic Reference Counting because it's not quite as simple as throwing away all retain and release keywords. Everything you need to know about automatic reference counting is also a thorough post on the topic.

In terms of accessibility, ARC makes iOS a lot easier for new developers.

`UIAppearance`

I've always struggled with meeting client expectations in terms of application appearance. Apple's iOS apps tend to have intricately themed interfaces, and while the default widgets and colours are adequate, corporate branding soon rears its ugly head and forces me to write lots of custom UI code.

The first tool in my application skinning arsenal was stretchableImageWithLeftCapWidth:topCapHeight::

UIImage *buttonImage = [[UIImage imageNamed:@"button.png"] stretchableImageWithLeftCapWidth:5.0 topCapHeight:0.0];

This makes it possible to create buttons with gradients, shadows, and rounded corners -- anything you can put in a PNG. iDev Recipes: Stretchable Images and Buttons is a good post on this because it includes a diagram showing how images get stretched.

Skinning buttons isn't enough for most clients. I think every freelance client I've had has demanded a background image in a UIToolbar. Not just a tint, but an image. I typically subclasses UIToolbar and change drawRect to draw an image. This solution goes against the general wisdom that, if possible, subclassing API classes should be avoided in Objective-C. Incidentally, there's an interesting on Stack Overflow about this very topic: Is subclassing in Objective-C a bad practice?

We now have an adequate solution for application-wide skinning through the UIAppearance protocol. It's now possible to skin an entire app with very little code:

UIImage *navBarImage = [UIImage imageNamed:@"images/menubar.png"];
[[UINavigationBar appearance] setBackgroundImage:navBarImage
                                   forBarMetrics:UIBarMetricsDefault];

UIImage *barButton = [UIImage imageNamed:@"images/barbutton.png"];
[[UIBarButtonItem appearance] setBackgroundImage:barButton
                                        forState:UIControlStateNormal
                                      barMetrics:UIBarMetricsDefault];

UIImage *backButton = [UIImage imageNamed:@"images/back.png"];
[[UIBarButtonItem appearance] setBackButtonBackgroundImage:backButton
                                                  forState:UIControlStateNormal
                                                barMetrics:UIBarMetricsDefault];

UIImage *tabBarBackground = [UIImage imageNamed:@"images/tabbar.png"];
[[UITabBar appearance] setBackgroundImage:tabBarBackground];
[[UITabBar appearance] setSelectionIndicatorImage:[UIImage imageNamed:@"images/selection-tab.png"]];

Given suitable high quality 24bit PNGs with subtle shadows and textures, your app will now blow your client's mind.

Blocks

At first I thought blocks were pretty needless, because after years of working with asynchronous APIs in Objective-C I'm comfortable with delegates. After using blocks in a project I'm now a convert. I actually write a lot of JavaScript, so I'm a master manipulator of closures, and I feel like some of the same code organisation techniques transition to Objective-C.

What convinced me was actually something unexpected: Parse. Parse is a service aimed at mobile developers that provides a backend that can be used to sync user data. It can handle user registration, password resets, and arbitrary structured data and files. While iCloud is great, Parse allows us to sync our data across iOS and Android, and potentially more platforms in the future -- all without having to write a web app.

Parse's code samples have a button for displaying code that uses blocks or callbacks. This is an example of block-based code:

[PFUser logInWithUsernameInBackground:@"myname" password:@"mypass"
  block:^(PFUser *user, NSError *error) {
    if (user) {
        // do stuff after successful login.
    } else {
        // the username or password is invalid.
    }
}];

Once the reader understands the block syntax, this code is immediately understandable. Contrast this to the callback-based code:

// First set up a callback.
- (void)handleUserLogin:(PFUser *)user error:(NSError **)error {
    if(user) {
        // do stuff after successful login.
    } else {
        // the username or password is invalid. 
    }
}

// Then, elsewhere in your code...
[PFUser logInWithUsernameInBackground:@"myname" 
                             password:@"mypass" 
                           withTarget:self
                             selector:@selector(handleUserLogin:error:)];

As Objective-C developers we know the second part of this code is in another method, and that's the key. Blocks keep related code together. As long as your block isn't too large, this is easier to follow and therefore potentially easier to maintain.

Blocks are largely intuitive, but __block is a syntactical wrinkle that's worth learning properly. Apple's Blocks and Variables documentation covers this, but I also found Programming with C Blocks on Apple Devices useful as well.

All three of these of these features make iOS development more accessible to newcomers, so if you've been putting off iOS development, now would be a good time to jump aboard.

Changing APIs and Package Managers

2011-10-14T01:10:00Z

When I started programming there was a real ‘if it ain’t broke…’ mentality. At least, I think there was — this was in the 90s and I connected to the community through magazines, computer shops, and public domain disks (that’s disks with a ‘k’, as in floppy diskettes). I learned a lot of BASIC derivatives from magazines, and eventually picked up some books on C. Then I heard about K&R C at university and flipped through a copy at the library. I think one of my friends bought a copy, and I was envious because I couldn’t afford it at the time.

Then later on I started playing with Ruby, and there seemed to be a huge amount of experimentation and creativity within the community. I dimly recall trying to work my way through Japanese documentation and giving up, but I came back to it a few years later when a lot of English–speaking developers had jumped aboard. The creativity in the Ruby community seemed to solidify when _why became well known and cartoon foxes and meta–programming were everywhere.

Then I started working with Rails, and there was a new mentality of constantly refining and changing things, sometimes based purely on aesthetic preferences, but other times to genuinely improve APIs and libraries.

In contrast to this, I’ve dabbled with Objective–C over the years and got paid to write several iPhone apps. I started taking Objective–C seriously partly because the iPhone was such a phenomenon, but also because I like C–like languages. Apple’s APIs don’t change fundamentally, perhaps because they were based on solid principles established by engineers at NeXT in the 80s and 90s. I’ve found I’m extremely happy writing code with events in Objective–C, and data storage is trivial thanks to Core Data.

Meanwhile, I’ve enjoyed building Node apps because I like event–based code, and JavaScript’s first class functions suit me as a Lisp hobbyist who never gets paid to write Lisp. Another reason I enjoy Node is npm’s move away from system–wide library installation, which makes dependency management easy.

Node’s core developers and prominent library and framework authors seem to be acutely aware of how frustrating API changes are. In some ways JavaScript and Objective–C seem to inspire a smaller range of API designs than Ruby — Ruby libraries will come with anything from a DSL to a simple object that can be called with public methods. JavaScript library APIs are usually designed around simple objects or chaining, and Objective–C APIs use a range of design patterns, Apple’s APIs in particular are focused around patterns that suit GUI development.

It can be frustrating to work with Rails when API changes create unexpected problems. The Ruby community has always had a culture of testing, which fits a dynamic language. Tests are generally part of the development process, so code can be updated to reflect API changes with a manageable cost in terms of additional testing and time.

API changes can be mitigated by locking down every library to a specific version. That means mastering a language’s package manager is now a core skill, rather than something that can be picked up on the job. It’s equivalent to the build process in a compiled language. Don’t write your Gemfile or package.json without putting serious thought into how library versions should be locked down. Certain contexts and libraries can generally be on the bleeding edge, others should be locked to a specific version. Also learn the features of your package manager -- I wouldn't like to develop npm modules without knowing about npm link.

Google+, Privacy and Engineering Consent

2011-09-04T01:09:00Z

At dConstruct 2011, Don Norman gave a talk entitled Emotional Design for the World of Objects in which he said Google’s main product is us and the service they sell is advertising. The services Google make aren't just a way of getting eyes on adverts, but a way of gathering information about us to improve advertisement targeting. If this is true, where is the evidence? And what does it mean for social products like Google+?

It’s now possible to link Google accounts together, which can make the awkward necessity of using several Google accounts more manageable. I have Google Apps accounts for work and personal use, as well as an obligatory Gmail account for services the Apps accounts can’t yet access. I’ve linked these together to make it easier to switch between them. Does this mean I’m now represented as one person internally within Google?

Google’s Privacy Policy seems to indicate that this could be possible:

We may combine the information you submit under your account with information from other Google services or third parties in order to provide you with a better experience and to improve the quality of our services.

This doesn’t specifically mention linking data between accounts, but implies information may be shared between services. There’s actually a page called Ads Preferences that shows what Google’s advertising knows about you, based on an anonymous cookie. According to the associated documentation consent is required before collecting personally identifying information:

We will not collect, sell, or share personally identifying information from ad serving cookies without your explicit consent.

This is interesting, because “explicit consent” in our field is something more malleable than it sounds. What it amounts to is agreeing to terms and conditions, which people do on a daily basis without having to read or understand. It’s entirely possible that I’ve already explicitly agreed to linking my personal information with Google's anonymous advertising cookies without even realising it.

This brings to mind two things: The Engineering of Consent and subsequently Manufacturing Consent by Edward S. Herman and Noam Chomsky, and Eli Pariser’s filter bubble.

The Filter Bubble is an ongoing argument against personalisation through technologies like Google’s advertising profiling:

Increasingly we don’t all see the same internet. We see stories and facts that make it through a membrane of personalised algorithms that surround us […] The filter bubble is the personal, unique universe of information that results and that we increasingly live in online.

Digesting all of these ideas around online advertising and privacy ethics finally leads me to this: Your name and Google+ Profiles. Google+ demands real names, and accounts have been deleted for using names other than the name on your birth certificate, driving license, and passport. If Google wanted to be in a position to clearly build accurate profiles of people, account linking and real names would be the way to do it.