Clever Hamster

On the trail of clarity, beauty, efficiency, and universal design in technical communication.

  • Home
  • Portfolio
  • Professional Activity
  • LinkedIn
  • Twitter feed for updates
Print
Top 200 Strategists
Recommended Blog - indoition
Doc-To-Help MVP
LavaCon Speaker

Categories

  • Agile (35)
  • API (3)
  • Cohousing (3)
  • eLearning (2)
  • Homestead (4)
  • Professional (9)
  • Technical Writing (68)
  • User Experience (8)
  • Web/Tech (27)
See More

Recent Posts

  • Writing Great Error Messages
  • How asynchronous meetings speed Agile
  • Growing tech pubs on top of Confluence, like Salesforce.org
  • Why "Clever Hamster"?
  • Road to Cohousing: People over Things
  • ATX Aging & Innovation Summit
  • So, why cohousing?
  • Quick space deletes in Confluence
  • Documentation-Driven Design: Moving the Caboose
  • Keep Austin Agile 2016 Takeaways

Cool Reads

  • Winifred Gallagher: Rapt: Attention and the Focused Life

    Winifred Gallagher: Rapt: Attention and the Focused Life

  • Anne Gentle: Conversation and Community: The Social Web for Documentation
  • Chip Heath: Made to Stick: Why Some Ideas Survive and Others Die

    Chip Heath: Made to Stick: Why Some Ideas Survive and Others Die

  • Thomas Limoncelli: Time Management for System Administrators

    Thomas Limoncelli: Time Management for System Administrators

  • Nassim Nicholas Taleb: The Black Swan: The Impact of the Highly Improbable

    Nassim Nicholas Taleb: The Black Swan: The Impact of the Highly Improbable

  • Timothy Ferris: The 4-Hour work Week: Escape 9-5, Live Anywhere, and Join the New Rich

    Timothy Ferris: The 4-Hour work Week: Escape 9-5, Live Anywhere, and Join the New Rich

  • Seth Godin: Small Is the New Big: and 183 Other Riffs, Rants, and Remarkable Business Ideas

    Seth Godin: Small Is the New Big: and 183 Other Riffs, Rants, and Remarkable Business Ideas

  • Thomas L. Friedman: The World Is Flat: A Brief History of the Twenty-first Century

    Thomas L. Friedman: The World Is Flat: A Brief History of the Twenty-first Century

  • Eric Abrahamson: A Perfect Mess: The Hidden Benefits of Disorder--How Crammed Closets, Cluttered Offices, and On-the-Fly Planning Make the World a Better Place

    Eric Abrahamson: A Perfect Mess: The Hidden Benefits of Disorder--How Crammed Closets, Cluttered Offices, and On-the-Fly Planning Make the World a Better Place

Archives

  • April 2021
  • January 2021
  • November 2020
  • August 2019
  • May 2019
  • November 2018
  • July 2018
  • February 2017
  • July 2016
  • December 2015

Pages

  • Portfolio
  • Professional activity
  • Topics
Subscribe to this blog's feed

Writing Great Error Messages

These resources for authoring error messages were just shared on the Write the Docs Slack community, by Monique Semp; they were too good not to save! (On the free plan, our WTD content goes away after a time.)

If you're not on the Slack community, get on over: writethedocs.org/slack 

  • Error Messages: Examples, Best Practices & Common Mistakes
  • Are there any industry-standard best practice guidelines available?
  • User Interface Text: is it OK, Now?
  • Message Text - moremiscellany
  • Messages (Windows)
  • How to Write Error Messages: Faster, Stronger, Better - Technical Writing Tips
  • The art of the error message – The Style of Elements
  • How to write better error messages
  • The 4 H's of Writing Error Messages
  • How to Write Error Messages
  • Error Message Guidelines (Nielsen Norman Group)

April 19, 2021 in Technical Writing, User Experience | Permalink | Comments (0)

Reblog (0) |

Documentation-Driven Design: Moving the Caboose

This month's Write The Docs ATX meetup featured Ian Buchanan, Senior Developer Advocate at Atlassian: Future-Proof Your Tech Writing Skills with Specification by Example. He was inspired by reading Specification by Example: How Successful Teams Deliver the Right Software (Gojko Adzic, 2011), which is deservedly famous. It describes the holy union of software requirements, project documentation, and test automation: (1) collaborate widely on requirements, (2) specify them through tests, and (3) automate their validation, so that the tests serve as a living documentation of the requirements. Ian's thought was that test-driven design should not be limited to internal use: it could and should be surfaced to example-driven design, meaning code embedded within user documentation, code that runs and validates.

Sadly, tech writing does need to be future-proofed. Writer teams are shrinking while release cadences are accelerating. Expectations for doc quality continues to drop along with its resourcing, driving the worsening problems that Ian identified:

  • Dead but not gone - Interfaces that are documented are no longer available
  • New but not seen - New interfaces exist in code but are not documented
  • Broken but not detected - Interface changes cause doc examples to break invisibly

Ian's brainstorm is to elevate and code up doc examples to serve as living external specifications that are automatically validated: they show errors when they're broken. This makes docs more valuable, visible, and trusted (as are, by extension, the writers!). The TDD cycle (write the unit test, test fails, code to test, test passes) would be expanded by one layer: example fails, unit test fails, and so on.

I latched onto the idea of moving up documentation work immediately after specification, before any tests and coding. What if we weren't talking about just the code examples in the docs but rather the entirety of the user docs themselves?

The seed of my discontent was planted by the owner of an enterprise product that I documented 20 years ago. He was keen on single-sourcing of any kind (shared code, cross-platform docs, docs and training), and he saw opportunity to streamline RFPs as well. Prospects in this vertical market were used to buying custom software, so they commonly required delivery of official specifications, to hold as contractually binding as to promised functionality. He decided that the product documentation could serve that purpose well enough, and so the documentation became the living specification, by decree. In short: if the docs said foo was possible, then the dev group was on the hook to make it so.

Yet the development process didn't change to match that implied path (describe the interfaces in example-rich user docs before coding them): documentation and training remained the caboose at the end of the waterfall line. However, Agile software development is slowly bringing product documentation into the fold, so perhaps the time has come?

Picture this:

Stakeholders work with the development team to settle on a list of specifications. Tech writers work with PM/BA and UX team members to develop documentation drafts that cover all of the proposed functionality. They capture the key use cases and motivation (user goals) and create interface mockups, diagrams, and meaty scenario-driven examples. In my experience, nothing sparks clarifying conflict like a diagram: making it visual forces people to recognize their own mental model and reveal their assumptions to the group.

My pitch: Let us host the constructive battles over usage, naming, task flow, and consistency before a single line of code is written, and let user docs be that highly visual battleground, the living specification, slowly morphing into the final deliverable (mockups become screenshots, pseudocode examples become real code). With such documentation to work from, writing test plans becomes much easier. This also prevents engineering waste: developers can reconsider implementation paths based on the emerging doc details, which improves the odds that they find an optimal one. It's excruciating to redo code and tests because of missing the goal; it's even more painful to just ship it and live with the awkward implementation!

To future-proof tech writing, let's move the caboose of documentation up behind the engine of requirements. Get us up front so that we can actively drive CX, rather than having us passively document around (and merely grieve) the interface that was coded as a result of unaired assumptions. Truly Agile teams would stop seeing documentation as a necessary expense but as central to getting the product forged in the first place, and that would change everything.

February 27, 2017 in Agile, Technical Writing, User Experience | Permalink | Comments (0)

Reblog (0) |

Keep Austin Agile 2016 Takeaways

The 4th annual conference for Agile Austin (Keep Austin Agile) was high-energy, plush, and well-attended. The day was a bit of a blur for me, with the excitement of presenting my session and doing interviews, such as for Agile Amped. But after weeks of noodling on what I heard presented and discussed, I found that several notions started forming up in my mind:

Agile lives, but Sprints are aging

In several sessions and table discussions, agilists complained about the nature of sprints, that their cadence is necessarily disruptive to the creative process. This definitely echoes the laments of my coworkers on Scrum teams: "As soon as we ramp up (cognitively) on the feature, it's time to shut it all down arbitrarily, just so that the sprint can end." Although the x-week sprint does put a stake in the heart of Waterfall projects from hell, it does so by forcing Waterfall into a tiny box (a sprint), where it can do less harm. Within the confines of that box, the mini-waterfall lives on, with downstream folks (QA, docs) bearing the brunt of the crunch.

Looking toward Lean and Kanban

I heard much longing to find a way to lower the stress and remove the mini-Waterfall box altogether, with lots of exploration of Lean and Kanban concepts. People sighed at the dream, noting that a truly unbroken stream of development would require far, far better epic and story development than most shops know how to do, and I agree. Dragging down velocity is murkiness — about the architectural big-picture, the integration impacts and touch-points, the implicit requirements and forgotten dependencies — none of which Scrum, with its myopic focus, handles particularly well.

To remove this murkiness will require, perhaps, a willingness to rebalance our teams, to add more analysts and architects. Even (gasp) add more writers, so that we could move the product documentation up to the pre-coding phase, to force stakeholders to grok and argue about what's being proposed before the team commits any code. (Most teams would find it faster to code to and test against documentation-as-specification rather than dream it up from stories.)

Just this morning I saw my longing for Lean mirrored in a piece by Tom Johnson: Context switching and efficiency -- Kanban to the rescue? Perhaps it's time to pursue this. Definitely time to read up.

Scrum of Scrum must be visual

Related to the search for a better way to work was a search for a better way to see. I attended a talk about the need to achieve a comprehensive Portfolio view across teams. He described a physical method: cards (one per feature/epic) posted in swim lanes on the director's glass wall, to show whose urgency was bumping what from completion, with notes explaining the situation. I've also worked with that physical method, once on the director's glass office wall and once on the wall to the break room, and my experience says it's critical to keep the cards small enough to preserve the big picture at  glance — if it sprawls too much, the brain truncates it. 

The goal of Scrum of Scrum is to break teams out of their silos and make everyone aware of and responsive to the fires flaring over the cube walls. Unfortunately, relying on whisper-down-the-alley from short-term memories of those who managed to attend is inconsistent at best, and distributed teams are even more disadvantaged. We need a visual SoS, so even just a table that summarizes the cross-team statuses is a step towards grasping the whole:

However, to truly defeat team silos with a visual board, I think hand-maintained systems can get us only so far. We need our tools to automate this for us, such as Portfolio for JIRA, for shops using JIRA.

July 15, 2016 in Agile, Technical Writing, User Experience | Permalink | Comments (0)

Reblog (0) |

WritersUA Central takeaways

For my own benefit, I'm writing this quick list of goodies and action items from the notes that I jotted down from the Software User Assistance conference this week:

  • Remember "pave the cowpaths" — let users develop footpaths and use those to decide where to put pavers.
  • Seek out books from the Visual Quick Start and Missing Manual series.
  • Study CSS3 selector syntax for controlling subordinate elements:
    • td p { } = styles only paragraphs within table cells
    • ol > li { } = styles only items within numbered lists
    • h1 +h2 { } = styles only Heading 2s that immediately follow Heading 1
  • Study CSS3 for methods to add @content, without JavaScript.
  • Breaking news of MadCap buying Doc-To-Help = evidence of client-side tool shakeout.
  • Visit Neospeech to hear surprisingly natural text-to-speech, available in Adobe Captivate.
  • Remember elearning rule-of-thumb: accessibility compliance adds 30% to dev costs; use Captivate with all accessibility options enabled.
  • Research says: Yes, use narration, but make sure that it doesn't read the slides! Distracts.
  • Simplify demo recording by doing voice over existing visual or visual with existing voice. Stand and smile, for best results.
  • Use variables to swap out generic verbs (select, scroll, move) with device-relevant ones (tap...).
  • Use onfocus events to drive dynamic embedded help: onfocus="readxml('objectname')".
  • Use 1-per-topic unique elements, such as DITA's short description, as a handy place to source and extract embedded help text.
  • Consider putting embedded help strings in minimal XML files, but be sure to convert any HTML tags.
  • Look up CanIUse to quickly find out what CSS3 is supported, where.
  • Use Dave Gash's webfonts page for samples, links.
  • Take the easy path to @font-face when possible by using Google fonts with big families.
  • For non-Google web fonts, let FontSquirrel generate the needed CSS3.
  • Turn to HTML5rocks for terrific tutorials.
  • Follow Don Day's progress with the ExpeDITA Framework, for making DITA web-CMS-friendly.

January 08, 2015 in eLearning, Professional, Technical Writing, User Experience, Web/Tech | Permalink | Comments (0)

Reblog (0) |

Chromebooks at work?

I've been madly in love with my Samsung Chromebook ever since I shamelessly stole it from my early-adopter husband (and I'm not the only one who's done this, I've found). Its tiny price, feather weight, cool operation, and long battery life perfectly fit my use case for couch surfing and family travel. My high-schooler is now inseparable from her $99-refurbished Acer as well. Chromebook seems like an ideal consumer product. (Not so Netbooks, which, if you recall, dragged and groaned trying to run Windows on cheap hardware.)

But now I think I spy ChromeOS poised to storm the enterprise as a "does enough" thin client OS, despite organizations' significant fear of relying on the cloud. From what I see, demands on IT are only increasing:

  • Reduce IT dependence and complexity
  • Provide hyper-portable devices
  • Lower hardware/software costs

More importantly, a convergence of must-have features is brewing:

  • Offline mode, for getting work done without network access
  • VMWare and Citrix support, for remoting to full desktop applications

With the new "desktop-as-a-service" (DaaS) subscription model, Chromebooks can serve up virtual desktops, not just web pages. That's a game changer that I can carry to a meeting, a client site, or a coffee shop!

October 08, 2014 in User Experience, Web/Tech | Permalink | Comments (2)

Reblog (0) |

pptPlex adds Prezi power to PowerPoint

Office Labs (yes, that exists!) has come up with a Prezi emulator, what it calls "Plex technology". It's a plug-in to PowerPoint that lets you not only zoom in and out of slide sections but also vault between slides that are not sequential in the deck. This type of dynamic behavior makes establishing and maintaining context in the big picture much more natural. Done well, it reinforces understanding and improves retention.

It's easier to understand what this functionality adds and how to use it by watching it in action. Here is the pptPlex Overview video.

Not sure what happens when it leaves the Lab, but for now you can download pptPlex and use it for free.

July 01, 2014 in Technical Writing, User Experience, Web/Tech | Permalink | Comments (0)

Reblog (0) |

Drupal Gardens as a tech pubs community platform

Looking for a cloud-based platform for social publishing (books, media) and community support (forums, blogs)? One that works off-the-shelf the same day and that you can afford?

Check out Drupal Gardens. It's Drupal 7, fully hosted by Acquia (enterprise Drupal specialists who offer solutions and support). I find the pricing unbelievably low for what it includes, and its main drawback is actually a great benefit.

Let me explain: Because Drupal Gardens supports a very controlled set of modules, they can commit to keeping your site upgraded and working. Those of you who have maintained web CMS tools know of what I speak: those lovely plug-ins and clever customizations that you depend on to meet your requirements make you vulnerable to your platform aging and breaking. Even without them, migrating your site to a new major version is often postponed indefinitely because of the breakage and effort it involves. Yet not staying current is a security risk, making your site vulnerable to hacking and loss. With this kind of controlled hosting, the product experts are responsible for keeping your platform updated for you, to the latest technology versions, fixes, and enhancements.

So, just how limited is limited? Within that set of modules that Drupal Gardens allows us to use, I verified that I could enable content access control as well as the Book module with page-level versioning and roll-back, which are the key pieces needed for tech docs. It also offers complete access to custom CSS theme development, content tagging, web forms, and more.

I verified with support that a few critical features we need are not yet supported, specifically: workflow around pending and published content, and the ability to insert reusable content at will within other pages (versus adding a boilerplate before or after page content, which you can). It's frequently the case that such features already exist, but they are not (yet) among the core set of Drupal Gardens offerings.

My hope is that someone will create a hosted distribution of Drupal that specifically builds out the features needed by technical documentation, which is a worthy vertical market. Drupal can do just about everything, if only someone puts the right pieces together! And if it's happening and I missed it, please let me know. :-)

May 30, 2013 in Agile, Technical Writing, User Experience, Web/Tech | Permalink | Comments (0) | TrackBack (0)

Reblog (0) |

Speed Queen and User Experience

Many years of torment with flakey front-load washers just ended with my purchase of a Speed Queen washer: a throw-back with spin dials and aggitator and all. Even though Consumer Reports poo-poo'd it per features, the hundreds of glowing reviews I read around the web persuaded me to hope just one more time.

She's not pretty, clever, or quiet, but I don't care. The love I feel is driven by great relief and happiness over the fact that she does just this: washes so well and so fast! reliably!

SpeedqueenSpeed Queen didn't teach me anything revolutionary so much as remind me of what was important. The lessons I want to recommit to my heart for every user interface and piece of documentation I design are these:

  • Offer a few great features
  • Design for the simplest/lightest/lowest usage and make that sing
  • Know their pain (don't assume!) 
  • Know their functional minimums, the absolute least they can succeed with
  • Serve the 80%: avoid distracting with edge-case options
  • Make it work the way they expect and hope
  • Make it easy for them to guess what to do
  • Make them confident that they know exactly what they'll get
  • Make them trust that they can't break it

For example, the fact that you can open the washer at any point in the cycle to check or intervene is a terrific inherent feature; I read endless rantings against "advanced" locking features on washers that prevented this. So, if the 80% don't need it, just walk away from the shiny option.

User experience is all about pain and pleasure, fear and triumph; may my Speed Queen always remind me to keep it simple. Fewer knobs, but good ones. :-)

December 11, 2012 in Agile, User Experience | Permalink | Comments (0) | TrackBack (0)

Reblog (0) |