The Hiltmon

On walkabout in life and technology

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.

Simple C++ Testing With Catch in Xcode

Catch is a simple, open-source, dependency-free unit testing framework for C++ projects. In this post I show you how to use it in a Simple C++ Project from Xcode.

Why Catch?

I am writing fast C++ libraries for work and need to wrap them in unit tests to ensure that they continue to operate and perform as they evolve. My number one constraint is that these libraries must be dependency-free. The only tools that I may use to compile or install these libraries on any platform (in my case OS X and Linux) is a C++11 compiler and a C++ standard library. Nothing else.

This dependency-free requirement precludes the use of excellent popular testing frameworks such as Boost Test (a dependency), cppunit (not up to C++11 yet), google-test (uses a dylib or library depending on the platform) or XCTest (Xcode only and not C++).

Catch is a single header only, dependency-free, lightweight testing framework that’s perfect for my needs. It’s simple to add to a project, simple to create tests cases and scenarios and simple to run. It also allows the user to run only a subset of tests using tags, which is really cool.

And that’s why I chose it.

Install Catch

Just include catch.hpp in a target and you’re halfway there.

The catch.hpp file can be downloaded from http://builds.catch-lib.net/. You can find the full source at https://github.com/philsquared/Catch.

Sample Tests

Catch is well documented. I recommend you follow the tutorial for simple functional unit tests and how to use the product. Since there is no point in me repeating how to write simple tests, go ahead and read through the tutorial, and I’ll wait until you return.

PLAYS ON-HOLD MUSAK

Ok, back? Good. You have seen how simple it is to spin up a TEST_CASE, break it down into several SECTION elements and test results using CHECK and REQUIRE.

Lets do something more complex, lets test a sample class. This sample project is what I used to test Catch when I first saw it and helped me choose it.

First, the tests:

test_sample_class.cpp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#include "catch.hpp"

#include "SampleClass.h"

TEST_CASE("Testing Sample Class") {
  SampleClass sc;

  SECTION("setting the str") {
    INFO("Using TestStr") // Only appears on a FAIL
    sc.setStr("TestStr");
    CAPTURE(sc.getStr()); // Displays this variable on a FAIL

    CHECK(sc.getStr() == "TestStr");
  }

  SECTION("test bigStr") {
    sc.setStr("TestStr");
    REQUIRE(sc.bigStr() == "TestStr : 7");
  }

  SECTION("Test doubles") {
    sc.setD(1);
    CHECK(sc.getD() == 1);
    sc.setD(1.0/3.0);
    CHECK(sc.getD() == Approx(0.33333)); // Nice
  }
}

In this example, we have a single TEST_CASE and three sections. Inside the TEST_CASE we instantiate the object and each SECTION tests a function in the sample class. Note that in the example, I arbitrarily switch between CHECK (no stop test) and REQUIRE (stop test), whereas in a real testing environment, I use them appropriately.

Here’s the sample class that we’re testing’s header, it really is quite a useless class but gives us a range of things to try:

sample_class.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#include <string>

class SampleClass {

public:
  std::string getStr() { return _str; };
  void setStr(const std::string& s) { _str = s; };

  double getD() { return _d; };
  void setD(double x) { _d = x; };

  std::string bigStr();

private:
  std::string _str;
  double _d;
};

And its body:

sample_class.cpp
1
2
3
4
5
6
7
8
9
10
#include "SampleClass.h"

#include <sstream>

std::string SampleClass::bigStr()
{
  std::stringstream ss;
  ss << _str << " : " << _str.length();
  return ss.str();
}

Testing In Xcode

I setup testing in Xcode using a separate tests folder and a second tests target and scheme. In this sample case, the main project code is in the SampleProject group (usually a library project) and the test target code is in the TestSampleProject group. This group (and its matching file system folder) are automatically created when you add an Xcode command-line target.

To create this target, select the project at the top and click + or choose File \ New \ Target from the menu, choose OS X \ Application \ Command Line Tool, choose C++ as the language and give it a name.

I then add catch.hpp and edit the main.cpp file. The main.cpp in the test target uses the default Catch main function, there is no point in writing my own:

main.cpp
1
2
#define CATCH_CONFIG_MAIN  // This tells Catch to provide a main() - only do this in one cpp file
#include "catch.hpp"

I also add the following command-line options to the test target scheme and toggle when needed:

  • -r console sets up readable console output (not necessary but a good reminder)
  • -d yes shows the time taken on each test (usually disabled)
  • s verbosely displays tests (usually disabled)
  • You could also add any test tags you want to run as an option, but I find most of my test projects run sufficiently fast that I usually leave this out and run all tests. It also protects me from forgetting to run the full test suite.

I then start to add .cpp files for each test case and write my tests.

Finally, you also need to add each class that is being tested to the Test target as well or it will not compile.

Running the test target delivers the following console output on success:

1
2
===============================================================================
All tests passed (8 assertions in 2 test cases)

If any test cases fail, you get:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TestSampleProject is a Catch v1.0 b53 host application.
Run with -? for options

-------------------------------------------------------------------------------
Testing Sample Class
  test bigStr
-------------------------------------------------------------------------------
/Users/Hiltmon/Projects/Spikes/TestCatch/TestSampleProject/testSampleClass.cpp:13
...............................................................................

/Users/Hiltmon/Projects/Spikes/TestCatch/TestSampleProject/testSampleClass.cpp:26: FAILED:
  REQUIRE( sc.bigStr() == "TestStr : 8" )
with expansion:
  "TestStr : 7" == "TestStr : 8"

===============================================================================
test cases: 2 | 1 passed | 1 failed
assertions: 8 | 7 passed | 1 failed

Correct the failures. Then add more tests. Run. Iterate, iterate, iterate. You know how to unit test.

Sample Project

You can download the sample project to see how it works from here.

Experience

I have been using Catch for several weeks now in multiple C++ projects and it’s been wonderful. Setup is easy, adding test cases is simple, running tests is a keystroke away and evolving my core dependency-free libraries is easier and more reliable than ever.

My thanks to Phil Nash (@phil_nash) for creating and maintaining this wonderful tool.

Follow the author as @hiltmon on Twitter.

Gist TextMate Bundle Updated for Yosemite

Thanks to Michael Sheets, the Gist TextMate bundle now works in TextMate 2 on Yosemite. The issue was that the UI code in TextMate 2 relied on Ruby 1.8, and Ruby 1.8 is deprecated and no longer installed in OS X 10.10.

Michael created a shim to fake Ruby 1.8 until such time as the code base moves to Ruby 2.0, implemented the change in the Gist bundle and it’s working now.

You can get the source at GitHub or just wait until it gets propagates via TextMate 2’s bundle update process.

Follow the author as @hiltmon on Twitter.