It can’t be just me, right?

Thursday, June 5, 2014 Posted by

IMG_0770A dear friend recently blogged about his experience years ago dealing with a situation in which the ‘problem’ was an “is it them or is it me” kind of scenario. He mused on the fact that in the face of everyone pointing to him as the problem, it really wasn’t him, that in fact, the problem really WAS with everyone else.  It’s a hard place to be, but luckily he came out of the situation well and can look back if even with a hint of smugness and know he was indeed in the right.

But, like my friend, when you’re deep in the thick of it all, it isn’t quite as easy to see the truth. When we, as individuals are in the middle of situations that are degrading at a rate forcing action, we don’t have the luxury of detached observation that we are afforded with time and experience behind us. In these cases, when we are in the middle of a situation, it is often hard if not impossible to see our own truths for what they are and guide us to the right choice.

I’ve recently been wrestling with this same feeling, the “is it me or is it them” feeling when it comes to a lot of socio-political issues. I have an odd dichotomy of emotion where my confidence in truth is shaken, while simultaneously being reinforced and strengthened. I wonder if I am really as smart and progressive as I think I am, or if I really did miss the memo and am off in lala-land with the other nut jobs who think similarly to me? When you’re in the thick of a cultural shift, conviction to your ideals is essential albeit difficult for fear that in some small way you may be wrong. After all, the crazy people are convinced of their certainty, and totally unaware of how crazy their ideas really may be.

When people I respect, consider friends, and look up to hold views in contrast to my own, I wonder how otherwise very intelligent people don’t see the world as I do. How can they not see the same truths as I? Surely they have more experience, deeper knowledge, and greater intellect than me, so how can some of their beliefs be so out of step with my own as to seem almost backwards? It is in times like this I begin to reflect on the “is it me, or is it really them? Are so many of them really that wrong, or are my own ideas the problem here?” questions that shake my convictions just enough to cause doubt and deeper contemplation.

I guess it all just means I am still a work in progress with no real answers yet…

A social quandary

Thursday, May 29, 2014 Posted by

IMG_0140I’ve often heard the adage that one must never discuss such off-putting topics as religion, politics, or sports at the dinner table. That adage has, of course, been levied as appropriate for any social interactions, be it at the dinner table or in the broader world of social media.

I used to subscribe to this idea, and still do for social business. After all, when it comes to business, professionalism is tantamount and none of those topics really have place for discussion in business dealings. However, I am starting to question the validity of such a phrase in personal relations. Are we to hide our head and ignore a deep undercurrent of cultural shifts simply because we don’t want to rock the boat or engage in passionate discussion?

I know of some people recently who have begun to filter out any religion or politics from their feeds on social sites, while I also know of others who actively seek out people to follow whom hold conflicting or opposite views as themselves in an effort. But I’m conflicted. There are days when I want to bury my head in the sand and forget that not everyone thinks like I do, to ignore the strife and arguments, and live in my cozy world of denial… and then there are other days in which I want to shout from the mountaintops and help steer a cultural/social shift to what I believe is the right way of thinking; to fight for progress and demand the change we need for fear of losing our humanity to cultural implosion.

I’ve been sharing a few sociopolitical posts recently, but in doing so realize that I am likely sharing with people whom already share similar views or opinions, as I generally surround myself with like-minded people. So, in effect, I am preaching to the choir and the people I want to reach will never read, nor likely understand what I share. It puts me in an echo-chamber, or a vacuum of social sharing at times, which really just equates to mental masturbation whenever I share something I believe to be provocative and progressive.

While social media has done wonders for us to engage in these conversations and raise visibility to problematic ways of thinking, it also has a dark side of deep judgment and polarizing effects when passions rise. To this end, I try to retain as many of my network connections as I can, regardless of their socio-political views, as I do believe that being open to seeing opposing views is a great thing and can only serve to improve me as a person. Insulating myself to only those people around me who agree, makes for a silo-ed existence devoid of growth and understanding.

What I strive for (and often fall short of) in my own life both on-line and off, is a balance. To think critically about any questions posed, any statements made, to ask questions with respect and desire to learn, and to take personal responsibility for both my words and my actions. Can you imagine how the adage would change if we all worked to think critically and take personal responsibility? No longer would sports, politics, or religion be taboo at the dinner tables or social gatherings, instead perhaps, they’d be welcome topics driving growth and understanding rather than the divisive and polarizing realms in which they currently exist.

I have a lot more rumbling around in my head here; So many recent events are tied so deeply and complexly together at their roots, that touching on one without acknowledging others is a disservice to truth and will only serve to cause more of the same cultural divide, the polarizing us/them/this/that false dichotomies that I so desperately wish to avoid. Yet, they are so complex in and of themselves that each could be a thesis of their own.

My takeaways from WriteTheDocs 2014

Wednesday, May 7, 2014 Posted by

IMG_0802

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:
    • Zapier.com 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).