Archive for category Work

Change is the only constant

Posted by on Monday, 10 August, 2015


It is somewhat of a bitter-sweet day for me:


Yup, today I officially resigned my ownership of the Notes from Rational Support blog, and all other associated social accounts. I had actually transferred duties to a new team of colleagues over the past month, in part to help cover for me while I vacationed last week, but in a larger part to take the space and bring it to even higher levels of value. But today it all comes to a pivotal point where I’m letting go of my ownership access to the blog as part of my continued transition in to the IBM Internet of Things support organization where I am working on social business strategy and logistics like I did for Rational Support since 2008.

As you may have already noted from prior posts on that blog, I am leaving it in the very capable hands of Denise McKinnon and Naomi Guerrero. I couldn’t be more pleased to leave this institution in their hands, much like Kelly Smith did for me a few years back. Kelly started the blog in 2009, and drove it to great heights in the beginning, so much so that when I took the lead in 2012 (and then the reins when she transferred to newer opportunities in 2013) I was quite daunted and unsure if I could keep the blog as valuable and relevant as Kelly had. Thankfully, I saw the value climb as I pulled in other authors to aid in content creation and to provide deeper technical topics for our clients. This helped us continue the climb in value and finally saw the blog hit and maintain the #2 most viewed blog on developerWorks for the past two years running with over 17 million views to date!


My pride in what we’ve achieved with that particular blog space is hard to miss, and of course makes it even harder to step away. Even harder still is the fact that it has been part of my daily life since I began helping Kelly in 2010. But, as I noted in my farewell post on Notes from Rational Support and in the title here, change really IS the only constant, and with that I have to acknowledge my time to move on…. Thankfully, I’m not moving far!

While I no longer run the IBM Rational Support social accounts, I AM still involved in social at IBM. More specifically with the IBM Internet of Things support teams. Now I hear you asking… What IS IBM IoT Support? And THAT, my friends, is a great question!

IBM IoT Support is a team of IBMers who are now part of the new IBM Internet of Things organization supporting the tools makers like our clients need to build components and connected devices. IBM IoT Support is focused on helping our audience, the makers, with their product questions by providing content relating to the various products covered by our new division.

Through our focused support of asset management and continuous engineering tools, we are here to provide our clients with the best support in the industry; to help them be successful with the applications and components to ensure your work on the connected devices in the Internet of Things brings you the right value.

To that end I’ve been working the past few months to create a few new social channels like our Notes from IoT Support  blog, our new Twitter account, and our new Youtube channel So you can see, I’m still doing the same job just in a different division of IBM. Of course I still have my hands deep into social support strategy as well as the day-to-day administration and content curation of our social channels and often act as a consultant helping colleagues in similar spaces navigate some of the speed bumps we all encounter in social business. Turns out, that is one of my favourite parts of this job: helping others be successful in their own areas of focus, which I guess is a trait that helps me be successful in my own areas as well.

Reminiscing with my day job blog posts

Posted by on Friday, 19 December, 2014


In building out some year-end blog posts for my day job on Notes from Rational support, I realized how some of my thought-leadership focused posts were maintaining some nice traction. While I’ve missed a few months of posting here I thought I might collect some of those top-viewed posts to highlight, if for nothing else than posterity showing part of what I’ve been able to accomplish on NFRS (now the #2 most viewed blog on developerWorks and over 12.5 million views to date). Here’s the top 16 of my op-ed/thought leadership posts in descending order of most viewed:

Of course some of these posts are re-purposed and published from this blog as a test bed for some of my ideas around social business. Of course I’ve a lot more where those came from, which you can read by browsing through the social business category here.


My takeaways from WriteTheDocs 2014

Posted by on Wednesday, 7 May, 2014


Apparently everyone at a tech writers conference has impostor syndrome. It seems the deeply technical nature of documentation is partially responsible for writers to feel like impostors when working alongside skilled developers. That, along with deep API documentation and treating docs as code, were the three long running themes throughout WriteTheDocs 2014 held at the Crystal Ballroom in Portland, Oregon this past Monday and Tuesday. I don’t know of any other conference that can compete for the price paid. I most certainly got a solid benefit from my $100 corporate ticket.

Rather than try to translate/ regurgitate my own session notes in this blog post, I’ll point you to Andrew Spittle’s blog where he live blogged each session’s notes (seriously amazing skill there!) along with the page hosting the videos of each session if you care to check out one of the many amazing sessions presented at WriteTheDocs 2014 (currently only 5 are uploaded, more to come I’m sure!).

Instead, I’d like to highlight two takeaways from some of the key sessions using the above blog post and videos as deeper context where you may need it.

  • Communities are awesome:
    •  Build community not minions. Work with your community on a common journey, not with intent to dictate.
    • Deal with churn early and up front, as this will avoid more painful and damaging churn at the end cycle of the release.
  • New Sheriff in Town:
    • Deputize your vigilantes. They have an intrinsic motivation that can be channeled for good. Give them power to change and provide focus to channel that motivation to improved docs!
    • Insert docs into product roadmap, dev, and life-cycle meetings. Remind all facets of the org that docs need to be treated as part of the product.
  • Ignorance is Strength:
    • Write docs by learning as you go. Use your ignorance to build meaningful docs from a new user perspective.
    • Write anything, even if it is wrong. Having something written can give a framework for improvement/ updates.
  • API Consumers are not who you think they are:
    • has great developer documentation of their APIs which allowed an unexpected audience to develop a use for their service they hadn’t expected.
    • Great developer focused docs which include text and screen shots / examples to explain the same concept in different ways.
  • Wabi-Sabi Writing:
    • Find beauty in the imprecise, the transient, the imperfect. But this is not luddism nor complacency.
    • Less Faulkner, more Hemmingway: less flowery, more simple and clear. Less Coltrane, more Davis: economical restraint.
    • Done is beautiful. (Art is shipped.)
  • Strategies to fight documentation inertia:
    • Talk to newcomers and beginners, ask them to write as they learn. Use “this section missing” stubs instead of blanks as motivators to complete that section by others.
    • Social engineer motivation to edit/update with strategic but obvious errors to fix. Use low hanging fruit to entice editors to make changes.
  • Improving Your Content’s First Impression:
    • Community outreach for feedback- export docs to community and import content from community.
    • Feed Stackoverflow questions in-line with documentation and embed feedback surveys.
  • Better APIs through Empathy:
    • Understand and share your user’s needs by using your own APIs.
    • Use other APIs and read their docs too. This will help you write for your user, not for you.
  • Ditch your CMS with Git and Static Site Generators:
    • Build your docs like you build the product you’re writing about. Use iterations and version tracking, then simply auto-generate your content with build commands.
    • Integrating developer tools provides consistency and familiarity across the development and docs process.
  • Documentation as a Product:
    • Like your product, answer the question: What problem are your docs solving?
    • Documentation can be marketing. A sales differentiator. Good docs can lead to client satisfaction, but you need to measure sentiment.

The net/net of the 2014 second annual WriteTheDocs? Would go again. I had a great time and was able to pull out some solid (as well as esoteric) takeaways from a short, local two-day conference. The benefit of being able to attend locally made this conference a seriously valuable event for me. Icing on the cake? A friend visiting and also going to the conference as well which made the event even better for me (friends don’t let friends conference alone).