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

Why "Clever Hamster"?

Well, a family joke: Whenever one of our hamsters (and we had several hamsters over the lean years of graduate school) found a particularly huge treasure (rotten potato slice, yard of yarn, birdseed bell), she would carve it up and hide it away in her nest with amazing enthusiasm and passion. Watching this, we'd tap our foreheads, look sly, and say "Clever Hamster!" After that, whenever one of us would have a bright idea, we'd do the same forehead-tap and "Clever Hamster!" cheer.

That's it. That's the story. (blush)

August 19, 2019 | Permalink | Comments (0)

Reblog (0) |

Road to Cohousing: People over Things

On the road to a future in cohousing, I have been on a dizzying journey: just this month, I moved to an in-town condo, and in so doing I have literally shed over half of my square footage and three-quarters of my family's accumulated material. Not that downsizing is so unusual: cross-country job hunters, house-poor retirees, the newly divorced, medical crisis survivors, and seniors face these kind of downsizing projects in great numbers, so often under duress. What may make me unusual is having embraced this pain before it was necessary. The upside? It feels better to go through the ordeal with some sense of personal choice, purpose, and control.

Redfin-sign

Why is downsizing so brutally hard? Beyond the immense physical drain of the effort, downsizing has crushing emotional and spiritual heaviness if it lacks empowering framing. Unless downsizing is the door to your vital future, it will be experienced as an agonizing series of losses (that was the kids' favorite TV chair; that huge Christmas tree was my dream). This is why we should be compassionate with our elders who fight relocation with what looks like irrational ferocity. "But I need you to be safe" rings hollow if it seems to come at the cost of everything she knows, relies on, and treasures, her comforts and very identity. The only way to reach peace is for her to see a vital future worth the change.

How I found my vital future, I realize now, was to define it in terms of cohousing, of moving into intentional, supportive community. I came to see that all-eggs-in-one-basket dependence on the nuclear family for emotional well-being perhaps works for some folks at some times, but it seems a poor strategy for the post-empty-nest phase of life, where households shrink and change and employment wanes. Space opens up in this phase of life, but our old suburban environment (which has ample busywork in the form of constant upkeep) lacks an organic means to infuse daily life with revitalizing and nurturing activity. Like a butterfly, we need to dissolve and rebuild ourselves to master what's next. Downsizing is our chrysalis.

Cohousing — short-hand for living in intentional community and sharing common spaces — has, at its core, the secret to downsizing: placing people ahead of things.

Things. During the nesting and chick-raising years, we become intensely thing-focused: rooms for kids; yards for pets; cars for errands; patio for parties; storage for decorations; upgrades for property value. Tremendous focus, time, and treasure goes into crafting our living space and all of its comforts and entertainments, all toward an imagined future in which we'll slow down enough to actually enjoy them. What we miss in that is the understanding that it comes down to Enjoy them with who, right now? Waiting around for grown children to visit relegates the bulk of life to gray in-between time, for many of us. And home improvement and maintenance, which we once met with ambition, now is left a tiring ritual detached from its prior urgency. Many punctuate these days with travel, but that can be largely a mechanism to flee the gray and fill the time. This heaviness is not a sign of a problem but of it being time to change. 

People. Cohousing is designed to encourage deepening of the community that calls it home. Like a retreat center, most cohousing prioritizes a central common space for people, to serve the needs of the group: a commercial kitchen, expansive dining/meeting room large enough for all, shared laundry and workshop/toolshed, yoga/exercise facility, guest rooms/suites, living/library room, art/craft space, community garden, car-sharing, and shared greens/playgrounds. The design encourages members to naturally spend ample time together in the community space and shared meals, so that private apartments can be smaller and simpler. Higher density is not only more cost-effective, but it facilitates easy interaction and connection, which is the heart of our vital future.

In the end, all of the things we worked so hard to buy were ultimately to be about enjoying ourselves with others we care for. When we firmly put people ahead of things (as I remember Suze Orman teaching in her financial training), we begin to correct our course. We see how our choices have become constrained by the needs of our stuff (cue George Carlin here), which is really backwards. We see how chasing security made us put our trust in things and neglect interdependence and community.

The problem is not finding practical help with downsizing strategy (you've doubtless heard of the delightful Marie Kondo and the book The Gentle Art of Swedish Death Cleaning, for example); the problem, I think, is deeper: how to want to downsize. That's where the vital future comes in: when we see living differently, living in community, as the longing of our future self, we can understand excessive things as being the barrier to that journey. We want to release whatever doesn't support us getting to that new home, which won't have space to house the museum of everything we've used and loved. Like the monkey who is stuck with an arm in the vase because he refuses to let go of any of the things he's grasping in his paw, we have to see that letting go of objects is the very means by which we can break free and get to a better place. 

And it is a better place. My new condo community has lots of retirees and single women like me, and every dog walk or trip to the mail can be an hour of happy greeting and getting acquainted. Just by eating my sandwich in the courtyard by the pool, I am easily approached by neighbors hoping to meet me or share some advice. There is comfort and belonging in this condo of a 100 households, where I already know more people than I ever did in the suburbs; how much richer and deeper will it be when there are only 20, and we share so much more?

May 13, 2019 in Cohousing, Homestead | Permalink | Comments (0)

Reblog (0) |

ATX Aging & Innovation Summit

The ATX Aging & Innovation Summit sold out again, but I'd gotten my ticket in time. This year's focus was "Aging in Community", which aligned perfectly with my interest in innovation in housing, especially cohousing and cooperatives. Highlights for me:

Design Thinking — A team of IBM facilitators gave us a hands-on workshop, training us how to use IBM's Design Thinking process to research and brainstorm solutions to hard problems: ignorance of services, isolation from community, and generational segregation.

Tech Startups — Mary Anne Connolly of MACMedia ran us through a panel of CEOs describing their startups:

  • Iris Plans offers a free service (paid by insurance companies) to guide seniors and the chronically ill through their health directives, using video conference calling with an expert to facilitate the family discussion with adult children.
  • Clairvoyant Networks is harnessing the IoT to support caregivers of memory patients: combining wearables with other sensors communicating over locked down wireless service, caregivers can remotely evaluate conditions, track location, and be reached in a button press.
  • Theora Care and CareStarter couldn't make it, but Guide Change, part of the Capitol Factory incubator, crunches data to spot potential financial mismanagement and even fraud from relatives, problems most commonly affecting older widows.
  • Remedy, already established for urgent care house calls (with compact testing labs), is now branching out into video-based telemedicine that progresses to house calls only as needed. The primary focus is keeping Medicare patients out of the ER, but the model is growing for providing primary health care via organization-specific portals. Unlike other telemedicine approaches, they don't lose patients over "what if I need tests?" worries.

Google Accessibility — The closing keynote was a sweeping overview of accessibility technologies and challenges, given by Henri Fontana, who is Technical Program Manager of Accessibility at Google. A version of this talk will be given at SXSW Interactive next year. I came with a solid background in accessibility requirements for software products, but this session was far broader and focused helpfully on a fuller range of disabilities and specifically on the issues associated with aging. For example, the more subtle cognitive issues that worsen with age include lessening ability to sustain concentration and lowering tolerance for cognitive load (multi-tasking), leading to frustration (easily overwhelmed and defeated).

Given that aging users increasingly need the support of smart phone apps and online services but find themselves less and less able to manage technology, see screen details, mouse and tap accurately, and type (much less type on tiny screens, given peripheral neuropathy), Henri suggested that smart voice technology (both speaking commands and receiving information) promises the most elder-specific benefit.

I imagine the elderly being able to use a smart speaker (Google Assistant, Amazon Echo, etc.) for an increasing list of tasks:

  • "Call Mary!" or, just "911!"
  • "Do I have an appointment today? When do I have to leave?"
  • "Schedule my ride to the bridge club."
  • "Raise the thermostat a few degrees."
  • "Order more Orange Gatorade and toilet paper."
  • "RSVP yes for the carpool to church."
  • "Play back 60 Minutes." "Slideshow my photos."
  • "Do I have any new email from family?"

There would also be more and more "push" assistance automation:

  • "There is a new weather advisory. Rain will turn to sleet by 6:30."
  • "Uber has been ordered and will arrive in 7 minutes."
  • "Take your evening medications now."
  • "It is Elaine's birthday. Do you want to call her now?"
  • "Put out the recycling for pickup by noon."
  • "Printing out medical history and medication list for Dr. Natov."

This is a major take-away that I've been thinking about: Combining smart speakers with smart sensors (data collectors on power plugs, coffee makers, motion detectors, electronic door locks, lighting, GPS wearables, and more), all manner of IoT data collection and analysis will make it possible to evaluate, track, diagnose, surface issues, and extend the independence of elders while supporting their family and caregivers.

Next year will be AustinUP's third technology summit, in doubtless a still larger venue, given that they sell out. I hope to attend and find out what Austin technology startups are doing in this space!

November 30, 2018 in Cohousing, Web/Tech | Permalink | Comments (0)

Reblog (0) |

So, why cohousing?

Now that I'm a member of a cohousing community in development (Ralston Creek Cohousing), folks are asking how I got into it. Truth is, I've been intrigued with the concept of cohousing long before I ever heard the term. Here's where my ideas came from, best I can remember:

  • As a tween, I watched The Waltons and noodled about how smart and supportive their multi-generational common house was; the older folks were able to contribute and also have the support they needed, the parents had many helping hands, and the children had the security of more adults to rely on. Living in an extended family seemed far more balanced than the nuclear family models all around me, which tended to result in too much responsibility being carried by the mother.
  • As a teenager, I read In This House of Brede (see Diana Rigg's great performance), and I was deeply moved by Phillipa's letting go of her glamorous professional life and dreamy apartment in order to join the deep sisterhood of a cloistered Benedictine community. I seriously considered becoming a Franciscan sister.
  • I commuted far to college and was socially isolated, but I stayed in graduate housing at UT Austin for my master's degree. Living with other graduate students from all over the country and the world, I learned how suite-style living with shared common spaces made for easy and ample companionship, and the shared meals in the dining hall were a wonderful way to enjoy that diversity of people. I was aware that it worked so well because we were all graduate students, so we shared a lot of traits (such as introversion), values, and interests. We were a tribe.
  • When I joined my first software startup company, several of the founders shared a large house, and several of the single programmers lived there as well. I envied the easy, fun lifestyle they shared. And the longer I worked in software shops, the more I realized that I enjoyed them because of the type of people who tended to work there, much like graduate school, and wouldn't it be nice to extend that environment outside of work hours? to live with your tribe?
  • I reconnected with an old coworker who, depressed, had quit his job and traveled broadly. Seeing him years later, I found him greatly transformed, and I learned that he had been living communally in the local Zen center for over a year. I was amazed at the benefits he'd gotten from Buddhism and from living intentionally. I wanted what he had.

About that time, cohousing surfaced. An email search reveals that I first mentioned "cohousing" eight years ago, hoping to interest my folks: "I found out about cohousing.org from a brilliant scientist whose blog I admire: http://earlywarn.blogspot.com/2010/05/odds-of-cooking-grandkids.html". Now I knew what to look for, but it was several years before my own path got serious. Then life happened: I divorced and empty-nested in the same year, so I stepped up my search for new intentional ways to live.

I started seeing and sharing articles about cohousing in Scandinavia, and I signed up for newsletters for cohousing.org and ic.org (Fellowship for Intentional Community). It was there that I learned about a Cohousing Association regional conference being held in Boulder, Colorado. Wanting the excuse to visit family in Colorado and wanting to tour and test my notions against actual cohousing communities, I splurged and attended the conference. Definitely worth it!

While in Colorado, I stayed at my brother's brand new house in a net-zero (carbon-free) development just south of Boulder, called the Geos Neighborhood. I learned that Geos had space allotted for a future condo-style cohousing unit, called The Gatehouse, just down the street from him! The community is still in the forming stage, so I joined to get in before all of the apartments were spoken for.

At the same time, I joined every cohousing and co-op group that I could find here in Austin. Sadly, those who have been working in this area for years tell me that Austin is actually one of the hardest cities in which to develop cohousing, due to the nature of its zoning codes. Just as disappointing, the CodeNEXT initiative that would have addressed this has just been torpedoed. However, there are multiple groups that are working on housing innovation, and I'm eagerly attending and supporting all that I can:

  • AustinUP, a community alliance, austinup.org (I just today attended their 2018 ATX Aging & Innovation Summit)
  • Aging2.0, Austin chapter: aging2.com/austin
  • Shared Equity Co-op, an informal group formed by co-op veterans who are seeking to develop new co-op properties for non-students
  • Armadillo Cohousing, a group that's in the early form-up stage

I'm very excited about the growing energy around making cohousing work in the United States, for more than just well-heeled retirees (although they deserve credit for driving this forward, as they look for alternatives to the sad senior housing experiences of their parents). I hope to contribute what I can to its success, as well as enjoy the experience of it! Anyone else?

 

November 28, 2018 in Cohousing, Homestead | Permalink | Comments (0)

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

Next »