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

How asynchronous meetings speed Agile

As my company was just acquired, I'm turning my attention to our organically developed Agile processes and noticing how it is that we stay so Agile and almost meeting-free. This just happened this morning:

While I was busy on a call, a lead developer needed some decisions finalized so that he could finish the UI for a new feature. Discussion in the Jira ticket had been progressing too slowly for him, so he started a Slack conversation with the product manager and with me, because the technical writer gets pulled into anything involving customer-facing language choices. 
 
In Slack, we hashed out the problems and questions, did some quick mockups, reworded the screen text, and thought through the implications for users. In only 15 minutes, development was unblocked, new language was approved, and I obtained key details I that I would be needing to make the documentation useful. 
 
Here are key benefits I spotted in this method:
  • Immediate — My dev lead didn't have to wait for the rest of us to be free for a meeting or wait for a standup to say that he was blocked.
  • Multitasking-friendly — The asynchronous nature meant that we were efficiently answering other Slack channels while we waited for each other to think and write up responses.
  • Documented — Unlike meetings, it leaves a complete written trail that we can search later for the details. We do record our Zoom meetings, but those are opaque to text searches.

I'm pasting the important bits of the Slack conversation into the Jira ticket so that we don't lose the history of what we decided and why. Our goal is always to make the ticket the repository of historical truth, so that a new person coming along later could reasonably catch up on the who, what, where, when, and why of the issue's life and jump in right from there.

How we came to this technique is, I think, a natural development of our being remote and distributed across time zones. To use everyone's time well, most synchronous meetings simply had to die. 

And that's a good thing. :-)

Don't get me wrong: it's lovely to see team mates; it's just that synchronous meetings aren't the way to get the most done. They are ephemeral, they bog down across time zones, and they don't scale. The efficient way is to use our messaging platforms for asynchronous meetings

January 26, 2021 in Agile, Technical Writing | Permalink | Comments (0)

Reblog (0) |

Growing tech pubs on top of Confluence, like Salesforce.org

Atlassian's abandonment of technical publication and help authoring as a key use case for Confluence is nothing new: 5 years ago they admitted it (CONFCLOUD-2522), and it explains our excruciating experience of being pushed onto a new Cloud editor that lacked critical functionality (50+ issues being tracked) that we rely on to author and produce our documentation.

Suppose that the economics of their market strategy are sound, and we're just not worth the development burden. What then? especially as our shops keep tight to the Atlassian stack?

Atlassian is becoming an enterprise platform that, in its broadening focus, needs considerable configuration with add-ons to fit any given organization -- much like Salesforce. And that comparison may suggest a path for us.

In 2008, the nonprofit community trying to use Salesforce started working together on the first version of NPSP, the Nonprofit Starter Pack, an open-source project to build out essential CRM functionality that most nonprofits need. It handles technical support via community-based forums and knowledge bases called Power of Us. All NPSP custom applications sit on top of the core Salesforce platform and evolve with it, all while being quite distinct from Salesforce's core mission of commercial B2B sales. Its separation from Salesforce is, I think, key to its unique success.

So, if technical publication is too niche a sector for Atlassian, yet we technical writers have a well-known set of common needs, could we not start a community to make this platform work for us? Could we have our own bundle of integrated add-ons that cover our needs for document control, version control, export design and automation, and more?

Confluence has always had add-on vendors who each cover portions of the tech pubs use case; premiere among them has been K15t. But the nature of Atlassian licensing has meant that the cost of assembling a huge collection of these needed add-ons is cost-prohibitive in most shops, end of story. It will never be the case that specialty tech pubs add-ons would or should be in the hands of most members of the organization, so pricing just never makes sense. My Support folks writing kbase articles use none of the power features that I do.

But what if we approached this as a community? What if we could license the bundle as a community member? What if the community entity licensed Data Center and enabled all the tech pubs add-ons, and we community members could pay for just the spaces and usage we incur from that shared whole? What if interested organizations could sponsor development on the add-ons and automation they most need, such as for translation control or exporting to LaTex? What if vendors such as K15t worked directly with the formal community of tech pubs users, which operated its own community-based forums and resources?

What if we each didn't have to go it alone?

November 12, 2020 in Technical Writing | Permalink | Comments (3)

Reblog (0) |

Quick space deletes in Confluence

If you’re moving or syncing spaces between separate Confluence instances, you may need to delete spaces so that they can be reimported. If you’ve tried this, you know that space deletion is a long-running process that can take literally hours and sometimes fails.

The most efficient way I’ve found to delete a space is to leverage the Replace feature of Import Word Document to dump the space contents before trying to delete the space. Doing this trick makes space deletion almost instantaneous.

  1. Start with a heading-free Word file, for uploading to Confluence: Download Confluence-dummy-import-docx
  2. Use it to replace the hierarchical contents of the space:
    1. Go to the home page of the target space (first link of breadcrumbs).
    2. Select … > Import Word Document.
    3. Browse to the DOCX you downloaded (or any DOCX but do not split by Heading).
    4. For Where to import, select Replace <space-name> Home and enable Delete existing children…
    5. Click Import.
  3. Delete the Trash:
    1. Go to Space Tools > Content Tools, Trash.
    2. Select Purge All, to flush the old space contents.
  4. Delete the space:
    1. Space Tools > Overview, Delete Space.
  5. Import the space:
    1. In source Confluence, create the XML space export (ZIP): Space Tools > Content Tools, Export, XML.
    2. Click the download link.
    3. In target Confluence, go to Administration (gear) > General configuration, Administration, Backup & Restore
    4. For Upload and restore a site/space backup, browse to the downloaded ZIP.

Hope this helps!

July 25, 2018 in Technical Writing, Web/Tech | 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) |

Capture Those Brain Dumps

Particularly in Agile shops, it's critical to grab information opportunistically: when that subject matter expert finally comes up for air long enough to discuss that new implementation you've heard was coming, drop everything and grab a basket to catch that brain dump.

By "brain dump" (dump as in download) we mean a person-to-person transfer of knowledge, often under a tight deadline (such as your expert leaving the company!) Sometimes brain dumps are live software walkthroughs, during which the SME flies through the online process, parenthetically rattling off dangers and limitations as well as future enhancements and open issues. It's what we lovingly call "drinking from the fire hose" because the information density is too high to be consumed, much less retained. In short, you're doomed: If you pay attention enough to formulate good questions, will you have taken sufficient notes? If you take good notes, will you have missed seeing the GUI process flying by on the screen?

In my experience, the best way to benefit from a brain dump is to make it a person-to-media transfer, to capture both the audio and visual information to disk so that you can review it after the fact and harvest out screenshots for reference. Use the time with the SME to pay attention actively and ask for clarification, and let the recording software do the work of capturing the details.

But how to record it? Aren't demo recording tools complex and expensive? Yes, those that are geared for formal training deliverables or commercial webinars cost real money; worse, they won't necessarily be easy to use in a brain dump situation, which won't likely take place on your computer (with your licensed recording tool) and your microphone. It can be even crazier when your SME is remote.

Here are a few tips and tools to get you started:

Don't make the SME do anything but dump.

  • In my experience, it doesn't work to ask SMEs to install special software on their systems or to be responsible for managing the recordings. Find a way that is completely hands-off on their part. They're harried enough.

Think MP4.

  • The MP4 video format is easily shared, uploaded, and viewed across platforms. From your Google account, you can upload this format to an unlisted YouTube video for quick distribution to team members. Done.

Start with what you already have, technology-wise.

  • If your company uses Skype for chat and video calls, just use Skype for the demo. Install the Evaer recorder ($20 for unlimited videos), start a video call with the SME, have them share their screen, and record just the remote video along with the combined audio. The SME can demo this way distraction-free, since they aren't doing the recording.

Seek out cross-platform browser-based services.

  • Most web conferencing services require a monthly subscription to record demos, but Zoom allows for local MP4 recordings on the free subscription. Create your account, invite your SME to your webinar, and let them share their screen and talk. If it's just the two of you, it's unlimited; for 3-50 participants, you're capped at 40 minutes.

If you've found other cheap solutions for capturing brain dumps, please share!

December 02, 2015 in Agile, Professional, Technical Writing | Permalink | Comments (0)

Reblog (0) |

Bulletproof numbered styles in Word

Oh, happy dance! I've been working in Microsoft Word again (for a content migration project) and I just broke through a major pain point: I figured out how to design style-driven numbered lists that won't go wonky or ever need restarting. If you use Word for technical publications, I hope this brings you joy.

The answer is to use a multilevel list, but with a twist. Multilevel lists are known to most of us as the way to achieve numbered headings, but they also let us create hierarchical structures for lists, both bulleted and numbered:

The trick, in a nutshell, is to create a multilevel list that starts with a "zero" level above the numbered list levels, so that restart numbering always happens correctly. That zero level (here, List Paragraph, Number0) is easily put to use as the standard intro blurb to the procedure:

Here's the plumbing:

  1. Create a set of styles for numbered lists based on List Paragraph.
  2. Create a new multilevel list (see red circle on toolbar, below).
  3. For level 1 (far left, under Click level to modify), select your zero-level style (List Paragraph) as the Link level to style.
  4. For Number format, delete the autonumber (none) and put in a character (for mine, I put a pipe and changed its color, just as a visual).
  5. For level 2, select your first numbered list style (Number1).
  6. For Number format, tweak it as you like (I removed the period and changed the font, for example).
  7. For level 3, select your second numbered list style (Number2). Tweak it as you like.
  8. Rinse and repeat.

Hope this helps someone!

February 13, 2015 in Technical Writing | 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) |

DocOps: technical content goes Agile

I'm watching the Acrolinx webinar recording, Learn How CA Technologies Broke the Rules - their DocOps Approach to Agile, with great interest, as it explores the "DocOps" concept in a tangible case study. The presenter is Jim Turcotte, SVP, Business Unit Executive, CA Technologies.

DocOps

DocOps (the merging of documentation into organizational operations) has these future-facing goals:

  • agility — respond and deliver changes right away (minutes, not weeks)
  • continuous updates — make fixes available immediately, trigger translation when needed
  • collaborative authoring — invite the crowd: let every team member add and fix content
  • customer integration — involve customer support and feedback; analyze usage and statistics
  • content aggregation — pull together all content, from marketing through support

In a nutshell, the CA case study describes a platform that is a "wiki++", where powerful tools extend a friendly wiki to cover all standardization, publication, and translation needs, and beyond:

  1. Collaborative authoring and aggregation: Atlassian Confluence (cloud-based, AWS)
  2. Documentation production: k15t Scroll, for Acrolinx integration, product version control, and product-specific output deliverables (be they wikis, HTML, Help, or Office/print formats)
  3. Automated editing: Acrolinx, for simplified technical English and standardization
  4. Translation management: Lingotek, for workflow in and out of the wiki
  5. UI integration: Product-specific landing pages integrate with web app, using single-sign-on
  6. Communication integration: Jive communities, Google Analytics, Salesforce support, LinkedIn marketing, etc.

CA already has some numbers that show measurable results, such as 25% word count savings (via consolidation), 55% faster translation turnaround, and close to 25% efficiency gains (from trimming doc activities now obsolete). But to my mind, such results are just icing on the cake of meeting the DocOps goals, which is the key to agile content that truly pays — up, down, across, and beyond the organization.

December 17, 2014 in Agile, Technical Writing | Permalink | Comments (0)

Reblog (0) |

Next »