The Hiltmon

On walkabout in life and technology

The Perfect Keyboard(s) (for Me)

I’m not a keyboard snob. But I love using my current keyboards now.

Background: I was very happy with the Apple “chicklet” style keyboards and even wrote about it in Not the Clicky Keyboard. There I declared that clicky keyboards were not for me.

I was wrong. But I did not know it at the time.

A while back, my boss went on a buying bender and purchased a whole bunch of different keyboards, including the DAS and some Microsoft ones. I tried them out too. Neither of us liked any of them, so he returned them all. As a joke, I ordered the CODE keyboard to show that I could buy “better” keyboards than him, and fully expected to return it.

The CODE Keyboard - I interrupted writing this post to take the picture.

The CODE is a keyboard designed by Jeff Attwood (@codinghorror) and assembled by WASD keyboards. It’s a big, black, heavy, back-lit, mechanical keyboard running the heavy and clicky Cherry MX Clear Switches.

Since I do not use a numeric keypad and like the mouse closer, I managed to luckily purchase the 87-key version with the rare Cherry MX Clears. I unpacked it and the initial thought was it looked like Battlestar Galactica compared to my sleek Apple keyboard.

I plugged it in and started to use it.

And no-one could be more surprised than I by the experience.

The keyboard layout was felt perfect for me. Better than the Apple one. Somehow my fingers found the keys I needed (and I am not by any measure a proper touch typist). The keyboard was the right size for my hands and it forced me to place my hands in a better position, which led to fewer aches at the end of the day. And best of all, there is no need to actually thump the keys down, they take pretty much in the middle. And I do like the clacky sound.

The only negative is that the pressure is a little high for programming. When I am writing, like now, my fingers tend to stay over the letter keys and the stiffer keys make me feel like I am working on some kind of modern mechanical typewriter. But when coding, my fingers move a lot out to the punctuation and numeric keys and I found the tension when pushing with an extended finger a little wearing.

So I ordered another WASD keyboard. I got the exact same 87-key layout, but with Mac keycaps and the lighter Cherry MX Brown switches with dampening O-Rings. The only other differences with the CODE is the Caps-Lock light is red and there is no back-light.

The second WASD looks the same, but the keys are reasonably softer than the CODE and they take even higher up. As a result, I can use lighter presses to type on it which makes coding for me easier.

So now I have two of them. The CODE resides at home where I do a lot more writing and I love the heavier presses and back-light at night. The regular WASD resides at work where I program all day.

There are many who will correctly point out that $150 (each) on keyboards is quite expensive and that there are many cheaper options out there. Sure, if that works, go for it. But I believe that anything you use or touch daily should be the best for you and cost should not be a factor. Then again, I am using a $100 mouse, $1,000 screen and $2,600 computer so the WASD is not that expensive in the scheme of things. And I use them all day and all night, every day.

I therefore highly recommend the WASD keyboards (CODE or regular, 102 or 87 key) but not for snobby reasons. I just prefer the layout, size and feel. I seem to make fewer mistakes and enjoy the typing experience more because my hands seem to be in the right place. I have not found that experience on any other keyboards. They work best for me.

Follow the author as @hiltmon on Twitter.

One-Key Format Presets in Scrivener

I am writing a lot of business documents in Scrivener, and even though it’s the wrong way to do it, I use Scrivener’s format presets (think paragraph styles) to quickly format headings, bulleted lists and paragraphs in each sub-document. This way I minimize post-processing (and the business format is intentionally boring so I do not need any fancy layouts).

But it’s a hassle to have to take my hands off the keyboard to click through the Format / Apply Formatting / Apply Preset menu tree or hit the tiny format preset dropdown ¶a to set the current paragraph style. What I want is a single key-combination to apply a preset style.

Here’s how I made it happen.

Create your Format Presets

The first thing you need is to create the Format Presets you want to use.

To create a preset:

  • Select the paragraph you want to format.
  • Set the font, size, etc using the toolbar
  • With the paragraph still selected, choose Format / Formatting / New Preset from Selection from the menus and give it a name. Make sure this name is unique to the application, this is key.
  • Click OK when done.

You should now see the new preset with your name on the preset drop down and in the Format / Formatting / Apply Preset menu.

To manually apply this preset to another paragraph, select the new paragraph and then click the new preset off the menu.

Create the Keyboard Shortcuts

Open System Preferences, choose Keyboard and select the Shortcuts tab. Click on App Shortcuts on the left.

To add a new Scrivener Shortcut:

  • Click the Plus Button
  • Select the Application - Scrivener
  • Type in the name of the format preset. Note: The name must match the format preset exactly, one character difference and this will not work.
  • Hit the keyboard shortcut you wish to use
  • Click Add to save

To see if this worked, click on the Format / Formatting / Apply Preset menu in Scrivener and you should see your new keyboard shortcuts on the menu next to their names.

All Done

So now you can focus on writing in Scrivener and format paragraphs without leaving the keyboard.

Follow the author as @hiltmon on Twitter.

Merge Asana Projects Into OmniFocus (Updated)

A long long time ago in a galaxy far far away, I wrote a script to import Asana tasks into Omnifocus. If you ran it again, it would update the tasks in OmniFocus. See Merge Asana Projects Into OmniFocus.

I recently updated the script to work a smidge better with Asana and Omnifocus 2. The main changes are:

  • Date formats can be changed (for those of us not in the USA)
  • The Non-Project tasks now load

Setup

First, follow the instructions from the original post to set up Omnifocus and get your API keys.

Download the updated script from https://gist.github.com/hiltmon/d1f79e95dd11252ce6ca.

Open it in a text editor and insert Your API Key and Profile Name in the slots provided. You can also change the date format to suit.

class MergeAsanaIntoOmnifocus

  API_KEY = '<YOUR KEY HERE>'
  ASIGNEE_NAME = '<YOUR PROFILE NAME HERE>'
  SUBTASKS = true
  DATE_FORMAT = '%A %B %d, %Y at %H:%M:%S' # (Try http://strftimer.com to build your own)

Make sure the prerequisites are in-place from the old post and then run it

 $ ruby merge_asana_into_omnifocus.rb

Warning: This is just my script, it may or may not work for you. Backup your OmniFocus before running it the first time. And use at your own peril. Inelegant, alpha-level, probably quite buggy, my first AppleScripts, you get the drift.

But if you do use it, let me know in the comments or via Twitter. And if you have any ideas for changes or enhancements, let me know.

Follow the author as @hiltmon on Twitter.

Seeing the Bigger Picture

It is quite astounding to me that an astonishing amount of work is done and code written without any knowledge, view or understanding of the bigger picture. And yet no-one seems to have taken the time to consider just how remarkably ridiculous this common situation is. How can people be expected to perform at their best and create the best products when they have no clue as to what the big picture or goal is?

And yet that seems to be the norm.

I started thinking more about this topic yesterday when discussing the work our Quantitative Analysts were doing with them. They were keenly focussed on figuring out the best and most correct way to calculate the results asked of them, but were struggling to understand what the results would mean and how they would be used. Without that understanding, they were unsure whether they were even thinking about the problem in the right way. What they needed was context, the bigger picture. Once they understood how their numbers and results would be used in the business and how their code would be used on a calculation server, they were far clearer on what they needed to do and how to architect it better for the business. And a whole lot more.

I really do not understand how or why the big picture should remain such a mystery, but being the nerd that I am, here’s my weak attempt to codify the reasons for I think folks hide the big picture:

  • They don’t know: The person setting the task also has no idea about the bigger picture, commonly in a dystopian bureaucracy gone mad or larger organization (Can you tell the difference?)
  • They don’t care: The person setting the task is just trying to get paid and cannot wait until the 5PM go-home alarm, otherwise known as “It’s just a job” or “I work in the public service” syndrome.
  • They have no time to explain it: The person setting the task is under pressure to get it done, has a hundred other things to do and is handing off a piece to get it off their list, pretty much like every overworked Business Analyst out there.
  • You don’t need to know: The person setting the task does not work for an intelligence agency and likes to play power games, or “I’m the boss, just do it.”
  • You should already know: The person setting the task honestly assumes that the big picture is clear and has been communicated in the past, the home version being “I’m having a fight with my partner and they keep saying I should know why” scenario.
  • It does not matter if you know: The person setting the task is a control-freak douchebag, believes themselves to be a superior being and is just acting like a middle ages noble.
  • They don’t know that you need to know: The person setting the task genuinely does not know that sharing the big picture is a good thing. Point them at this post and they will receive a good, healthy dose of wonderful karma points.

From first-hand observations, the impacts of not knowing the big picture are many:

  • Duplicated or unnecessary processes, workflows and code because the folks involved had no idea that it was so. If they knew, they would find better things to do.
  • Inconsistent deliverables, products and results, where different groups producing the same things come up with different answers. Look at any large firm with multiple accounting groups and try to get a single picture of how the business looks.
  • Signs of disconnected, fractious, people fighting against each-other over small fiefdoms when the whole purpose of an organization is to work together to achieve the bigger picture.
  • Frustrations between groups and departments where the “other” is always getting things you asked them to do wrong, a refrain we programmers are so used to hearing.
  • Outright conflicts where one team’s work-product negates another team’s work product, and neither knows about the other.

Whereas, in the situations where the big picture and context is communicated first, I see:

  • Better architected business, workflows, processes and systems as everyone involved understands and is working towards the same big picture.
  • Requests, deliverables and systems better tuned to meet the needs, not the stated wants, reducing rework and frustrations.
  • Combines the intelligence and domain knowledge of the requester, programmer and worker/user to find the right, optimal and useable solution, not a quick and dirty one decided by a manager.
  • Gets the work done better as all involved have “bought in” and are motivated to succeed as a team.

Next time you set a task for someone else, start with the big picture and explain to them how the task fits in, how, where and by whom the deliverables will be used, and how it will make things better for others. Then, and only then, explain the work needed to be done. You will find that they will understand the task better, deliver better solutions, enjoy what they do more, and most importantly, give feedback insight into ways of doing it better.

Follow the author as @hiltmon on Twitter.

Eliminating Google Analytics Referral Spam

It seems that the Google Analytics use of a public tracking code was a mistake. Anyone can use your tracking code on their site, which adds to your traffic, or they can create ghost visits and spam referrals by hammering Google Analytics with your code while never visiting your site. Oh, and the codes are easy to guess, so they do not even need to know about your site.

In most cases, this is perfectly harmless (IMHO) as only Google Analytics data is affected and your reports look funny. Your ad stats, if not Google, remain the same as they are independent.

The only reason I am talking about this is because I was up early this morning and noticed that a page with the title of “Luck” was trending in my analytics1.

Except for one problem.

There is no post entitled “Luck”.

I never wrote one.

Ever!

Which led me down the rabbit hole.

You can spot these fake referrals pretty easily. Go to Reporting / Acquisition / Referrals on the Google Analytics site. Then, next to Primary Dimension, select Other / Behavior / Hostname:

My site is hiltmon.com, who the blazes is that?

Whatever you do, please do not visit that URL.

Michael Sullivan (@AnalyticsEdge) from Analytics Edge wrote two excellent posts recently on what these are and how to deal with this referral spam:

Go ahead, read them.

I have updated my Google Analytics filters and am waiting to see if the changes work. I have also created the segment as directed and that seems to work great, but only for some reports.

Follow the author as @hiltmon on Twitter.


  1. Still running Status Board by the seriously handsome folks at Panic on the original iPad.

StackOverflow Programming

StackOverflow Programming happens when much of the functionality of an application is copied and pasted from the code examples found on StackOverflow. Unfortunately, it’s becoming the most popular and common programming paradigm amongst younger programmers, leading to (1) shockingly shoddy, bug laden, slow, incomprehensible, unmaintainable programs that work only once, and (2) to programmers who do not understand what they are doing, their work and how to solve problems.

For example1, one of my interns came into my office this week to see if there was a way to do dates and times easily in C++. Java and C# both have easy Date Times classes, he said, why not C++? I told him C++ was a low-level language, and to use time_t and the std::chrono libraries like all C++ programmers do. Off he went.

But he was back in a few minutes. He’d Googled the topic, seen how horribly complex the default C++ libraries were, found no example code, and had come into my office to argue for boost::DateTime. He had one and only one reason in favor of using boost::DateTime - that there was plenty of example code on StackOverflow for it.

This intern is smart, he’s a master’s level student. And boost::DateTime is a perfectly good library. But still he did not argue, or even consider:

  • Why the standard C++ way was so low level?
  • Whether boost::DateTime was better than time_t? Or Worse?
  • What other DateTime libraries were out there?
  • Why his code should use the same DateTime as all the rest of the code in the system.
  • Why he should learn anything instead of copy and paste from StackOverflow and move on to the next step in developing the application.

I’m seeing this more and more. Junior programmers have grown up in the StackOverflow universe, finding answers in the form of paste-able code for any questions they may have on StackOverflow. Why should they learn, or understand, or take the time to figure out a solution when an answer is a Google search away?

And lets be fair, us mentors, leads, managers and the business do not help here. We assume savant level programming skills when planning and assigning programming tasks and the only way to meet these insane deadlines is StackOverflow Programming. Google a solution, paste it in, move on.

The result is shoddy, badly performing, unmaintainable, inconsistent code that we cannot use in production and must rewrite. Whether it’s the choice of tools to use, the libraries, the functions to implement features or otherwise, the result is code that delivers the results we need in a completely unsustainable way. And when there are bugs, and there invariably are, the poor programmer has no way to understand them, never mind fix them.

I am not presenting the argument that all StackOverflow answers are bad, most are absolutely excellent. I have had occasion when stuck to be helped by and try to understand many myself. And the ones I have provided are awesome, of course. My point is that the StackOverflow examples are just that, examples, to help the reader view a sample and try to understand a potential solution to their problem. They are not intended as production-level code snippets, but that is how they are being used.

I do understand, especially as a programmer, that re-inventing the wheel is a waste of time. And that having to write low-level code is a drag when there are potentially simple copy and paste options available. But I also understand that code changes, requirements change, code needs to be maintainable and robust and performant (especially when writing real-time systems) and that production systems need to be well understood and stable.

StackOverflow Programming is great for quick and dirty, one-off programs and prototypes. But for long-term, stable, production-level applications, the programmer needs to understand their tools, language, libraries and the code they write so it can be maintained, evolved and supported.

I love how people, myself included, have contributed to StackOverflow. And it has saved my bacon on many occasions. But we need to teach younger StackOverflow generation programmers that the answers they find there are just examples, nothing more. Examples that need to be understood, compared, evaluated and studied. Only then should the knowledge, understanding and skills gained be used in order to create stable, consistent, maintainable applications.

This way, we’ll all get more. Better applications made by better programmers. And better examples on StackOverflow from better programmers for existing questions.

Follow the author as @hiltmon on Twitter.


  1. Names and details withheld, and the story adjusted, to protect the innocent.

Write Timestamps Containing Milliseconds to MongoDB in C++11

It took me several hours today to figure this one out, so I thought I’d write it up lest I forget.

I have a C++11 application that rapidly writes new documents to a MongoDB instance and I need high-resolution timestamps to determine the order things were written.

The problem is that the C++ standard time_t structure reports in seconds, so

builder.appendTimeT("updated_at",
    std::chrono::system_clock::to_time_t(std::chrono::system_clock::now())
);

creates an ISODate without milliseconds in MongoDB.

There are many solutions to be found using Boost::time1, but since my code needs to be dependency-free and pure, I needed a C++11 clean solution.

MongoDB helps with its own Date_t class which is really just a long long number of milliseconds since the UNIX Epoch. So if I can generate that, we’d we dancing.

The solution in my utilities namespace, DateTime class is:

namespace utilities {

  struct DateTime {

    ...

    static int64_t millisSinceEpoch()
    {
      std::chrono::system_clock::duration duration{
        std::chrono::system_clock::now().time_since_epoch()
      };
      return std::chrono::duration_cast<std::chrono::milliseconds>(duration).count();
    }

    ...
  }
}  

This function constructs a C++11 duration object containing the number we need in an internal format, and then converts it to milliseconds for use.

The MongoDB c++ code also changes to:

builder.appendDate("updated_at", utilities::DateTime::millisSinceEpoch());

And now we have MongoDB ISODates with milliseconds that work perfectly.

Follow the author as @hiltmon on Twitter.


  1. Yes, I know MongoDB uses Boost, but all I do is link to MongoDB’s precompiled library, so my app remains plausibly independent. And I do not need to deal with matching MongoDB’s boost version with my own.

CodeRunner 2

Nikolai Krill released a major update to CodeRunner today, and I highly recommend it to all programmers no matter what languages you use.

In my case I write a lot of code in C++, Objective-C, Ruby, Javascript and HTML as part of large, complex projects. Often I am unsure how best to write a snippet or function. One way would be to create a branch in the project, run and experiment, deal with compiling, branch again to try another solution, compile some more and work it out. But that is a slow process (and quite dangerous if you leave these experimental branches in, or forget to branch at all).

Instead, I jump over to CodeRunner, select my language and attempt several approaches (in tabs) to solving the problem. I use CodeRunner to write, run, test and debug to figure out which solution is best. Once I get the code working, fast and looking good, I copy and paste it back into my project and keep going. No branching, no risk.

CodeRunner 2 is no longer available in the App Store, I’m guessing sandbox restrictions. CodeRunner 2 comes with a bunch of new features including Code Completion, themes, multi-file support and Yosemite support. It’s a paltry $9.99 as of writing (or free for those who purchased CodeRunner on the App Store).

Highly recommended.

Follow the author as @hiltmon on Twitter.

What to Write About Next?

I was asked in a blog comment today how I decide what to write about. And once decided, how do I go about doing it. In this case, the answer was easy, I decided to try to answer the question. And deconstruct the process I go through as it happens.

Instructions: Read this post in black font first, then come back and look at the gray which deconstructs my thinking.

Every story needs a starting point, I added the next paragraph in the second iteration of the post to create some context. And maybe to establish some kind of credentials and an authoritative tone. Why would you, the reader who does not know me, care how I answer this question. My goal was to show you that my answer to this question evolved, that it was not taught. And that I was surprised to find out I have been doing this for 10 years already.

I started writing on the web in November 2004, see my embarrassing On opening a new Account. I had no idea what I would write about when I started, so I wrote about that lack of ideas. How meta. But I started. And I wrote.

And looking back, it evolved into the three kinds of things I do write about:

  • Views or opinions on topics related to my interests or work.
  • Sharing something I have learned or done by write a reference post.
  • Take on fun writing challenges on a topic I am not savvy with.

But all my writing starts with an idea, a thought, an opinion or a challenge. Where do these come from?

The Ideas

I realized after the second iteration of this post - I had focussed on the three kinds of post instead of ideas - that I had failed to answer the primary part of the question: How do I decide what to write about. So I added this section. Knowing the three areas I write about got my mind onto thinking where these magical topics come from. The answer, I jot down ideas. All the time.

Over the years, I have become an inveterate note-taker. Having a blog and wanting to write means I need ideas. And since I have not yet figured out the voodoo behind when ideas strike or what triggers them, I jot them down as and when they do occur.

I have notes with single phrases in them. I have notes with tweets that triggered thoughts. I have notes that look like half-completed treatises of a madman. I have notes that go nowhere. I have notes that contradict other notes. I have notes that repeat or reinforce other notes. I have notes to remind me to write about other notes.

Whenever I come across thoughts, topics or ideas I could want to write about, I stop and take a note. A question, a tweet, another post, a sentence on a podcast, if they generate an idea, I stop and make a note. Then go back to what I was doing. The objective is to build a corpus of ideas irrespective of the quality of those ideas.

Later on, the same day, weeks later, whenever, when I sit down to write, I look through these notes. Most get rejected. For example, there is no point in writing that I agree with someone else’s topic without having anything to add to it, even if it’s the most interesting topic in the world. And there is no point writing about stuff that no longer looks interesting to me sometime later, after the idea has cooled off a bit.

Fortunately, I have enough of these notes that some remain after the great culling to work with. Which means I probably have something I could write about. But what do I want to say on that note’s topic?

That’s where the categorization comes in. Do I want to express a view on it and add to the discussion? Is it something I have learned that I can share? Or is it a just writing exercise, a silly idea to help me become a better writer?

I am sure you have guessed that this piece fits my categorization of a writing exercise. Can I think through and write about this topic, and actually get somewhere with it? We’ll both see.

The Three Kinds

I had never thought through this before today. I try not to write and share my views if they add nothing to the larger conversation. So what does add to this conversation? Time to drill into it and see whether an opinionated idea can pass a sorting.

Writing about my Views or Opinions

If I have an idea to write about, I need to decide whether I can add to the conversation. No point in writing if it adds nothing. Once again, looking back, it seems that the sorting looks at three ways to determine if an opinion piece gets written.

  • Determining my View, Point or Opinion: This seems like a contradiction, but often I am not sure where I stand on a topic. Writing on that topic, creating a story for it, walks me down that path. I feel that stories that help me determine my view are often useful to others to help them determine or understand theirs. And that adds to the conversation. For this to pass, the story must be good. For example: My Mac Indie Writing Workflow or one of the originals, The Markdown Mindset
  • Confirming my View, Point or Opinion: When I am sure of the point I want to make, I write my thinking behind that position. If the resulting piece adds no more to my position, it gets thrown out. But often, working through my thinking brings out stronger and better arguments for that position, and that adds to the discussion. For this to pass, the argument needs to be good. For example: I Choose Not to Be Anonymous or Go Home
  • Challenge or deconstruct my position: The contrarian in me loves to write these. I have a position on a topic, so I challenge it. Either I choose a contrarian position and write that, or I dissect my own thinking on it. I never publish the contrarian writings, how would readers know when I am being arbitrarily contrarian and when I am standing up for a point. But these experiments help me see the position in a different light and result in better deconstructions and analyses. For this to pass, the flow needs to be good. For example: The Markdown Payoff

If I am unable to construct a story, argue a position or build a flow, the opinion piece fails the sorting and never gets done. I feel that it would not be interesting for me to write or you to read, as it adds nothing to the larger conversation.

I noticed at this point that there are a lot of “I”’s in this post. I am standing on a soapbox talking about a self-invented process where I sort out ideas into ones I will argue and ones I will not argue. True. I was going to shorten this section but understood that its just one of three types of sorting I do, and topics rejected here may still have reference or challenge ideas in them.

Reference, what have I learned?

Many of my ideas come from what I do. I design and develop software. I enjoy new and exciting experiences and face new and exciting challenges in my sphere all the time. And when I find ways to do what I do better, I care to share. These are my reference topic ideas and they happen all the time as I solve new-to-me problems, try out new tools, or dive in where I have much to learn.

Reference topics include how I go about common processes, or how I use software tools or how I think about business, software and design. They can be dry and factual. They can have screenshots and code and downloads to make them more visual and helpful.

Reference topics cover the tools I use, the architectures I develop, the business topics I want to discuss. They also include product reviews, surprises I found, and new-to-me ways to do things.

The best part is there are so many ideas here that I have trouble sorting which to cover. Deconstructing my thinking leads me to filter them out unless I can answer the following:

  • Why. Why do something that way? Why use that tool instead of another? Why think about a topic in this way?
  • When. When should you apply this knowledge? When does it not work?
  • How. How is this way or tool better? How does this process do better than others?

I try to be clear in my reference topics. For example, I intensely dislike product reviews where the reviewer leaves the decision as to whether something is good or bad up to the reader. If a review talks about a product but does not have a why, when and how, then what’s the point of the review? Another example, a post on a data structure in computer science needs to explain why that data structure is good, when to use it and how is it better in that situation, else it too is useless. It’s a tough standard, but interesting is tough.

Reference topic writing also helps me in other areas. Explaining complex software constructs or convoluted business processes is hard. Writing about them helps me find the words to express them simply and clearly.

A reference topic, therefore needs to have one addition to the factual details, the why, when and how to apply the knowledge gained. For example: Xcode and the Simple C++ Project Structure or Letterhead - Markdown Style

Reference posts to me are the easiest to write though. I know something I did not before, and I am sharing that knowledge or experience. The story is easy as it’s the journey I took to learn or experience that thing. And my opinions do not matter unless they add to the story. Facts do. The hard part is clarity, making complex topics readable, understandable and reproducible.

Experiments, Writing Challenges, Fun

Its all good to focus on the few skills that you are great at and let everything else slide. But writing about a few limited topics limits my scope and abilities. If I only wrote about tech, I’d get quite boring quickly.

Thats where the fun ideas and challenges come in. In whatever you do, you should be stretching yourself. Whether that’s taking on bigger and more complex projects, changing industries, or building up new skills. If you are not learning or being challenged, you are stagnating. In writing, for me, that’s where I look for the challenges.

I want to be a better writer. I have a long way to go, and many mentors high standards to target. But if I keep writing about what I know and have always written about, I will no longer be stretching, learning or growing.

So I take on my own small writing challenges.

I look through the strange and silly ideas I have had, and, instead of rejecting them because they are hard or different, I challenge myself to write about them. And, more importantly, I publish some of them too. The feedback loop on these is very important to self-improvement.

Writing challenges are hard. You have an off-the-wall topic to write about and need to

  • Build a story
  • Have an opinion
  • Be interesting or funny
  • Create an argument

Most of these exercises fail. If I cannot figure out most of the above, the story gets sorted out. But those that I can build even the weakest of stories and arguments on, I work on.

The goal is to make me a better writer. And these challenges have certainly done so. I think my opinion pieces are better presented, and my reference pieces are clearer, all because I stretched myself in writing challenges.

The hardest part was publishing them. I’m no expert on etiquette (See Email Etiquette) or suitcases (see Buying a New Suitcase) or personal story writing (see The Day He Walked to Freedom) or making fun (see Every ‘the Best Programmers Editor’ Review), but I took up the personal challenge, and then put them out there. Ironically, they were surprisingly well received.

I did not want to talk about these challenges at first. They’re stupid exercises that I chose to do to see if I could become a better writer and have no place in a professional persona. But the reality is that they do work, and I seem to find myself being able to talk on a far wider set of topics than before, with greater comfort. It becomes a courage thing to write these challenges, and a courage thing to publish them. These exercises help me find newer ideas for topics to write about, and that is part of the answer to the original question.

Growing the Idea

The sorting process helps me decide whether to write about the idea. It also forces me to think about what I want to say. It is at this stage that I find myself drilling into the idea, thinking about it in more detail and clarifying what I could write on it.

It’s critically important to me to capture these thoughts, as I lose them later on. So I add them to the notes in point form. They are not fully thought out, just the random, unstructured fragments that come to mind while thinking about the idea. Later, I cannot understand half of what they mean. But at the time, it’s important to capture them.

These are not structured thoughts. They are the scattered ideas of a scattered brain trying to think through an idea. They can be structured and reviewed later, but they need to be captured first.

It’s not a formal process either. Brainstorming makes it sound like something you can learn and practice. Maybe you can, but for me its more like dumping a stream of disconnected consciousness into a note.

This section was the one of the last to be written because I really struggled to find the words for it. How does one describe an informal brain dump where your creative and analytical juices are flowing and the result is almost incomprehensible. And yet without this messy pile of random thoughts, I really struggle to fill out the topic with reasonable and useful information when in the process of writing in clear sentences.

Filling it out

So the idea has passed the culling and the sorting. In sorting I added many points I want to make to the note and now it’s time to write.

Early in the piece, I also got stuck here when deciding what to write in this part of the post. I was thinking how sometimes the point you want to make just flows and there is no need to plan, structure, prepare to fill out or justify that part. And other times you get stuck, a part of the story needs to be told but you have no idea how to started on it. So I rely on a few tools, like mind maps, like asking myself why this part needs to be told, or try to document what I was thinking at the time, or even ramble on a bit to see if I get anywhere. Revisiting the structure and the why helps me think through the part again. And write it better. And that reminded me to write the previous section - where did I get the stuff to structure it in the first place?

Some posts take minutes to write and they work. Other posts take months to think on and write on and never get finished. And a lot get rejected because they never get to any point.

For bigger posts, I draw up a mind map using MindNode Pro. If there is a lot to write about, I feel it is important to list all the topics and structure the piece. It also helps me arrange thoughts and ideas. It helps me build the story. It helps me focus on the parts that I need to think about and and write.

For smaller posts, I start with a point-form summary, or a document full of random sentences taken from my notes. No structure at all.

And then I fill each section out with words and paragraphs. I try to type what I want to say, the way I say it. I just write. I do not worry about spelling, grammar, or even what I am writing. I just try to get it down and out as if I were on a stage in front of people having just been given an improv topic to talk about.

Aside: I think I am one of the few people who do not mind being in front of a crowd with nothing prepared. I have not studied improv, but I did teach at university. And teaching makes you learn that you never know what questions a student will ask. So its best to be prepared, but better to be able to think on your feet. And that’s how I write at this part of the process. Of course, unlike public speaking, with writing I can iterate and fix it up later. Oh yes, that’s the next point.

And then I iterate. Just like a programmer does. I reread what I wrote, correct the spelling and grammar. I look at the clarity, did I make the point? Does it flow? What did I miss? Am I repeating myself. This is not reviewing the topic, this is unit-testing, checking each sentence that I have written to see that it says what I wanted it to say, and reads that way. And most importantly, does the sentence add to the story, the argument, the topic, or do nothing with it.

I digress a lot when I talk and think. These “thought bubbles” in this post are proof. But I do come back from digressions because my programmer mind brings me back to the original topic. I do not have a problem with digressions in writing, they usually add color to the story, but too many digressions and the reader will lose track. I try, not very successfully in my opinion, to limit these when I write by iterating and using the delete key frequently. I do not always succeed.

I also get stuck a lot when writing. At the time of making the note, culling or sorting I had great ideas for the post, but now that I am in writing mode, I forget those great thoughts because I am focussed on making sensible sentences. That’s where the structure, the necessity of a point for sentences and the notes help.

Review

At some point, I find I have filled in all the sections. It’s time to go back and see if any of it makes sense. So I review the writing by re-reading it.

The first few reviews are easy. The text is messy, it does not flow. Tones and tenses change. Ideas are still a bit jumbled. But now that the whole structure is filled it, it becomes easier to see where everything is, should be and how it should flow. It becomes easier to see where you repeat yourself, where you digressed, and where you lost the story’s plot.

My early reviews involve re-reading in context, deleting that which is not necessary to the story, and filling in the smaller cracks that got missed out while focussed on writing. It also helps me see if the story works or not. Many a post has gotten this far only for me to realize that the story or points are either nonsense, boring or make another point entirely.

So it’s more iteration, read, edit, write a bit more, re-read, re-edit, re-write.

It is a sad truth, but rereading what you write again and again makes you blind to the text on the page. You start to miss the typos and grammar mistakes. Your eyes skip over paragraphs because you “just know” what’s in them. You assume what’s there instead of read what’s there. That’s why editors exist. But us lone writers do not have any.

For some posts, the ones that just flow, review is easy. They flowed, the point was made, good to go. For others, more tricks are needed to fight text blindness. For me, these include:

  • Reading the post aloud (or at least with my lips moving, like I was reading a speech). It helps to see if saying the words flows as expected, and just by saying things, they either feel right or wrong.
  • Looking at it in a different context. I export to a drafts folder and view it in Marked.app or on the web. The simple trick of changing the look and location of the text undoes much of the reading blindness, helping me see how it works.
  • Time heals all. While reviewing you get blinded. Come back later after doing something else when your mind has been elsewhere and the piece looks and feels different. That’s the best time to re-read and review it again.

The Story

In reviewing this post, I realized that I had harped on a lot about telling a story. But had not yet explained why I think that. After I wrote this section, I noticed that it did not add anything new, every topic on writing pushes story over boring facts, and so I almost removed it. But I also felt the need to clearly point out that posts need to be interesting and the best way I know to make things interesting is to, wait for it, OK, you guessed it, tell a story.

A good post needs to be like a traditional story, it has a beginning, a middle and an end. A great story comes full circle, where the end circles back to the beginning.

For reference pieces, this is easy. The beginning is the problem definition, the middle is detailing the workings of the solution, and the end explains how the solution solves the problem. Full circle.

For opinion pieces, not so easy. The beginning needs to set the stage. Why do I have this view, opinion or position? What is going on that this opinion piece needs to be written? The body then needs to walk the reader through the argument or story. Take them from the pre-set stage, through your thinking to the points you want to make. The road may be straight - a simple story, an easy post - to quite wiggly - complex ideas, digressions, a difficult post. And you need an end. You need to bring the story to a close, to show how and why the opinion or view impacts on the stage and how and why it is to be viewed differently after reading the piece. It’s not a case of being right, it’s a case of presenting your thoughts, ideas and experiences, applying them and helping the reader see what you see.

For the writing challenges, it’s even harder. There may be no beginning other than the challenge itself - like this piece. The body may be a mind game, a list of dry facts, a made-up story, or a well-written dissertation. And the end is your new-found view or understanding. You then need to make that interesting. And that’s where a story overlay kicks in. For challenges, I try to put myself into the challenge. How did I get to this challenge, how did think about it, what did I learn, and how did my understanding of the topic improve. The end may be a good piece or a mess, but at least I learned something, and maybe the reader can too.

Either way, a story is the most common way we share information, its the most common way we remember information and its the most fun way to consume information. I don’t remember the Newtonian formulae for gravity, but I do remember the apple-falling-from-a-tree story.

For a post, a presentation, a speech to be interesting, it needs to couch the information it contains in a story. If that’s all you take-away from this piece, that’s good enough for me.

Fin

It’s time to end this story. Way too many words have been written already. And I think I have covered how I capture ideas, decide what to write and what I then do with it. Which means I have answered the question. Time to close the circle.

When I started writing, I worried about what would I write about, just like the individual asking the question. I did not know who my audience would be, and whether I should write for them or for me. I did not know my own voice. So I followed some good advice and just wrote for me.

Initially the topics were quite random, a lot more writing challenge style posts. But I did start jotting down all my mad ideas. As time progressed, I found myself writing more and more opinion and reference pieces. I still had no audience or voice. And then one day, I noticed that I did indeed have one. This one. And immediately set out to challenge myself to write better for me and my audience.

I get ideas from what I do, see, read and hear. I write about what I am interested in, where I feel I can add to the conversation and hope that you, the reader, finds some of it useful. I write in the form of a story where possible, as its the easiest to consume and remember.

But almost all of my writings all started as ideas in notes. They survived the culling and the sorting. They grew as I thought more deeply on the idea. They got written and reviewed and iterated on. Where possible, they told a story. Some were good, some not so much. But I intend to keep on doing it.

Now, what to write about next? Let’s look in the ideas folder again.

Follow the author as @hiltmon on Twitter.

Lose the WWW

I have finally removed the www from hiltmon.com. The 1990’s have passed and www no longer makes sense in URL’s. Maybe it’s time you did the same to your site too.

What triggered this change was that, as of 14 October 2014, Google Analytics started throwing an error if you had links to www.yoursite.com and yoursite.com. This is because it treated links with www and without as different.

Removing the www was easy. I used Global Search and Replace (⇧⌘F in TextMate 2) to find //www.hiltmon and replace it with //hiltmon. Then regenerated the site.

But we are still faced with the problem that remote links to the site may still include the www in their URL’s. The solution is a 301 redirect. Setting that up depends on your hosting provider. For Dreamhost1, it required clicking one radio button:

Welcome to hiltmon.com.

Follow the author as @hiltmon on Twitter.


  1. Warning: Affiliate link.