Archive for category Work

My takeaways from WriteTheDocs 2014

Posted by on Wednesday, 7 May, 2014

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).

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Don’t blame the tools

Posted by on Thursday, 1 May, 2014

Today, the Grammarly blog ran this image as the main bit of a simple post, noting the downside of short form communication:

texting_quote_1200x627-670x350

image credit via Grammarly at: http://www.grammarly.com/blog/2014/the-real-problem-with-texting/ 

As you may have guessed from the title of my post here, I disagree. But more specifically I believe it is they way we misuse the communication tools available to us for the wrong conversations. This hearkens back to one of my earlier posts on my business blog “Notes from Rational Support” during our drive to work outside the inbox: Using the right tools for the right conversations

In that post I outline how using open and transparent communication tools like blogs, wikis, and forums to collaborate on ideas before transitioning them into actionable work can be a wonderful method for building an efficient workforce. More importantly, however, is that using the right tools for the right conversations aide with improving communication all around.

Use the tools you do have available to consciously move those conversations away from short-form, email, or closed systems to the more open and transparent mediums and you’ll see your communication improve in an almost passive manner. Make use of forums and wikis and blogs to collaborate and drive your work forward, use texts for simple quick updates/questions, and of course pick up the phone and call someone when the conversation requires that deeper connection and free-flowing discussion.

Texting isn’t the issue with failed communication. The issue is using texts for the wrong conversations and not moving those conversation to the right medium when texting begins to cause confusion.

Information is currency; Privacy doesn’t exist

Posted by on Wednesday, 23 April, 2014

IMG_1955Earlier today one of my dear friends shared this article and tagged me for comment: Facebook Knows Everything About You, And If You Don’t Believe Us Here’s Proof

The article details out how UbiSoft’s marketing for their new game inadvertently shows how much Facebook knows about you. This is done via their Digital Shadow site after asking you to connect to it via Facebook authentication in which you grant access to your data as housed in the social network. The article paints a F.U.D. based theme (fear uncertainty, and doubt) around an individual’s privacy and how they may want to change their settings within Facebook to tighten things down.

Here’s the thing, though: there is no privacy on the internet. Security settings and custom privacy tweaks are speed bumps at best, and theater at worst. Like a glass window next to your home’s front door, any motivated attacker can bypass these settings with some small effort. While the addition of privacy settings are indeed necessary and effective to avoid the most common of breaches, they have also worked to the larger cultures disadvantage by allowing us to be a bit more complacent and reliant upon tools to do the job of privacy control. The best privacy control you have is the ability to choose what information you share.

Be careful, though. What you share may initially seem innocuous and irrelevant to most security or privacy concerns, but as the article above and the site referenced, there are things that can be inferred and connected across the data you share to build a view of your life which you may not have intended to be visible. Simple things like your location when combined with a job title can tell me a fair estimate of income as well as likelihood of work schedules and how valuable your digital life may be. The site does a good job of holding up a mirror to anyone sharing via Facebook and how that information can be connected to build a larger, perhaps unintended picture.

What does this really mean for you, as a participant on social media channels? It means you need to make informed choices. Understand that information is a form of currency used to trade for access to these sites and deeper connections to your networks of people. In my case, I trade quite a bit of information to maintain my connections with you while also working to build domain expertise in my career as a social business strategist. I make very specific choices about how open and transparent I am with what I share via any social channel, knowing that information is at best only obscured by my privacy settings and likely will be seen by many more people I’d not intended or expected. (Oddly, it is one of the lessons I’ve learned from blogging for so long now: you may be writing for one audience, but there’s likely other audiences reading and connecting… pay attention to them as well, as there may be wonderful opportunity for growth when you identify those unknown audiences).

We can’t trust companies to maintain our privacy for us. We need to take personal responsibility for our own information, what and how we share. While this may seem like a call to lock down your profiles, it isn’t. Rather, it is a call to become more informed and to begin thinking before we share and making the choice to use our information to pay for access or connection instead of just assuming it all comes for free. There’s a cost to social interaction, and what we are willing to pay will likely differ for every individual. Knowing that cost is the first step before paying the toll by sharing your information.