Stuff

Essentials

  • April 2017
    S M T W T F S
    « Sep    
     1
    2345678
    9101112131415
    16171819202122
    23242526272829
    30  
  • Facebook

Posts Tagged "stitcher"

How can technical writers thrive in agile environments? Event recording and details

Audio Recording

Listen to the recording:

You can download the MP3 file, subscribe in iTunes, or listen with Stitcher.

Agile panel event description

Here’s a description of the agile panel event:

How can technical writers can thrive in agile environments?

Most engineers in IT departments follow an agile scrum process: they track issues in sprints, assign and scope story points, meet daily to provide short updates on their work, and release updates every 2-3 weeks.

Technical writers who work with engineers usually find that being productive requires them to become familiar with the engineer’s agile scrum workflow. Whether you want to keep abreast of engineering work, factor in time for doc reviews during the sprint, or have documentation be managed like other IT work, you need to know how to integrate or work with the agile scrum workflow.

In this chapter meeting, we will have a panel discussion about how technical writers can thrive in agile environments. (See the STC SV event post for more details.)

Tip: If you’re new to agile and scrum, check out Jeff Sutherland’s book Scrum.

Panelists

The following 5 people were panelists:

Bonnie Clark has almost 20 years of experience in the technical communication field. She is currently a Director of Technical Publications at FICO, a leading analytics software company.

Rosemary Picado is the Documentation Team Lead at Sumo Logic, and works with agile and non-agile teams within the company to document their cloud-based log management platform. Formerly at Recommind, she transitioned from Tech Writer to Scrum Master while the platform was being re-architected, learning the value of Agile first hand, and how the skill sets intersect and complement each other.

Daniel Doornbos has been a technical communicator since 1982. He most recently worked as a Senior Technical Writer at HEAT Software on its IT Service Management product. The company is in the process of transitioning to agile development.

Jane Wilson leads the technical writing team for GE Digital’s Applications Engineering group. GE Digital develops in an Agile environment, and, as the team has grown, she has developed processes for fitting writers and the writing process into Agile methodologies. Along the way, she became a certified scrum master. Jane belongs to the East Bay and Atlanta chapters, and she currently serves on the STC Board as Treasurer.

Gina Blednyh is a Staff Technical Writer at Salesforce. She’s worked in an Agile environment for almost six years. She’s also been a scrum master for both a writing team and an engineering team and is an Agile convert.

I moderated the panel.

Questions discussed

Here are some of the questions about agile and tech comm that we discussed:

  • Should documentation be managed as items in an engineering sprint?
  • Should doc reviews be assigned story points?
  • Do you still create a documentation plan at the project kickoff if you are following an agile scrum process?
  • How can you keep pace in documenting features during the sprint if the features don’t get finished until the end of the sprint?
  • How can you reduce the tedium of daily standups when engineers seem to rattle on endlessly about coding issues?
  • How can you stay updated about JIRA items when engineers don’t take the time to articulate the issue but rather hastily add a quick title that only they and other engineers who are already familiar with the issue understand?
  • How can you persuade engineers to dedicate time for doc reviews if there’s no points allocated for the work in the sprint?
  • Logging bugs changes the role tech writers play on teams. Should tech writers log bugs when they find them, or simply send emails to the QA engineers to log the bugs?
  • What processes should tech writers follow in order to publish rapidly during the two-week cycles, especially when tech writers have several projects at once, all of which have two-week release cadences?
  • How can technical writers be valuable participants in the agile process when they are part of 3+ different teams, each of which has its own daily standups, sprint planning, and retrospective meetings?
  • Agile teams often follow a “fail quickly” approach that leads to coding in a lot of different directions in order to find something that works in the market. How can you avoid massive revisions of your documentation with each major direction during this highly volatile period of coding?
  • Agile teams often want to minimize the amount of documentation in order to stay agile and flexible (the principle is “working software over comprehensive documentation”). How do technical writers negotiate the de-valuation of documentation on agile teams (even if the docs mostly refer to project documentation instead of user documentation)? How does minimalism factor into agile practices?
  • What time management techniques can you implement to be more efficient in order to meet the fast-paced demands of agile teams? What can you ignore or cut out of your day? Are all meetings necessary to attend in order to convey the importance of your role on the team?

Share your experience

If you want to share your experiences with agile, you can do so in the comments on this post.

Implementing Swagger in your API documentation — My ISTC article

If you’re an ISTC member, then you already get the ISTC Communicator, and you can read my article in print or by logging into the ISTC site. You can view the table of contents for the Autumn 2016 here (but not the article content unless you log in as a member).

If you’re not an ISTC member, you can read my article here: Implementing Swagger (OpenAPI specification) with your REST API documentation, since I also published the article on my site in HTML format and integrated into my API doc course.

A lot of people ask about Swagger, and although I’ve written about Swagger previously, this is my clearest and most thorough article on the topic to date.

Balancing the never-ending list of documentation to write with your natural interests and passions

Listen to this post:

You can download the MP3 file or subscribe in iTunes.

Although most days are the same, they are a little different. My kids have returned to school, and so my summer routine of waking up “when I wake up” and riding my 8 miles to work along the scenic San Tomas Aquinas trail (which follows a half-dry canal) has changed a bit. I now ride my kids to school and then ride on to work. My two youngest (6 and 9) often glide along on roller skates while holding onto the back of a bike child carrier that I pull. My older two kids get themselves to school by bike and foot.

My wife is an early riser who leaves while it’s still dark and heads up to the “Dish” in Palo Alto to walk along a trail that is so popular, if you don’t get there before 7am, there is not a single place to park for what seems like miles.

The extra ride to school adds another 4 miles to my route, which puts my daily biking round trip at about 20 miles. When I also add in a few games of some post-work basketball, all the exercise can seriously wear me out. (Unfortunately, I still manage to eat enough calories to more than enough compensate for all the calories I’m burning.)

The fatigue from riding sometimes carries over into a sense of fatigue about endless documentation tasks. I’m still trying to follow Tim Ferris’ advice to focus on the highest two priority items first thing in the day and block out everything else.

Sadly, I’m lucky if I get one of the two items finished. Even if I do finish it, I usually can’t publish the documentation I write until I can get the right subject matter expert to review and sign off on the content – a process that can take anywhere from a few days to more than a week.

It would be more encouraging if I could see the to-do items decreasing little by little, but I think the reverse trend is happening. For every item I knock off my list, two more get added (both for tasks at work and at home). Sometimes I feel like I’m slowly sinking, and as much as I try to conquer the documentation mountain, it just keeps rising higher and higher in the sky.

I dream about a day when I’ll have marked every task as “Resolved,” like having reached a state of Inbox Zero. In this state, I’ll tackle incoming items with such a responsive velocity that those who requested the update would be surprised at how quickly I turned it around, like when you find that someone has responded to your email just seconds after you sent it.

It crossed my mind today that perhaps instead of writing documentation myself, the only way to truly scale and conquer this documentation mountain is to switch from author to curator. A marketer who works near me noted with glee how she already has four posts she is publishing on the company blog this week. Did you write them all yourself? I asked, ready to be impressed. No, she said, teams reached out to me with the content.

I’m not sure I would be entirely satisfied being a content curator instead of an author. Writing is my sweet spot, and where I perform my best (except for maybe setting up authoring tools). But no doubt a hybrid role of author/curator is essential to survive.

While the documentation tasks keep building, I’m also trying to build up my technical knowledge of Android and the products I write about. There’s a lot to building streaming media apps – it isn’t something one learns in a few weeks. What’s more, the developer audience is at such a higher technical level than I’m at, my documentation has to hit on the questions and gaps of knowledge they will run into, not just me. I just finished editing a document about 4K Ultra HD media that has so many details about refresh rates, color formats, codecs, and other specifications that I wonder if I’ll ever get to the point where I can consume this information as easy as reading a morning newspaper.

I try to get into work a bit early to push through some tech tutorials in the morning and at lunch, but taking time out of my mounting doc tasks to step through a tutorial is always a trade-off. Am I sharpening my ax, which will make it easier to chop down the tree? Or am I learning about something so disconnected to what I’m documenting that by the time the material becomes relevant, I will have already have forgotten it?

That’s the crux of ramping up on developer technologies – unless you’re immersed fully in the domain for an extended period of time, the info doesn’t entirely stick, and it slowly fades. Then months later you have a documentation task that requires the knowledge, but by then it’s only a dim memory.

One day I’ll be an Android master, and I’ll know these products inside and out. I’ll resolve all of my JIRA items, and I’ll find myself wandering up and down cubicle aisles chatting leisurely with colleagues because I literally have nothing to do since everything is done.

But that day is a long ways into the future, and I only have a vague idea of how it will be. It’s mostly a dream. I know that the longer I’m at a company, the more projects I work on, the more documentation I’ll become responsible for, and the less time I’ll have. If any bandwidth opens up, more projects will take hold of that bandwidth until it is maxed out. Maybe someday I’ll even have a “direct report,” which would require even more bandwidth.

Maybe it’s not the tech writer’s destiny to ever get a perfect handle on all the open doc tasks and master all the technology details. Maybe this state of slowly sinking but then somehow pulling myself up a bit each day is the permanent state of technical writing. Is this what makes the job interesting – the challenge, the steep learning, struggling against the insurmountable?

I reflected on this idea during several of my bike rides to work, in between listening to books on Audible. I’m currently listening to Ready Player One, by Ernest Cline. In the book, a brilliant video game designer (James Halliday) creates a virtual reality layer to every day life that becomes a new dimension that most of humanity interacts in. The earth has deteriorated, poverty has increased, and the only alternative to the dismal, gray, degenerate life on earth is the virtual world Halliday created, which he called the OASIS. (The book is set about 15 years into the future.)

In the OASIS, students attend school, interact with each other, and do pretty much everything that you would expect in a normal world – except that they do it by sitting in one spot wearing OASIS goggles, moving their haptic gloves (or haptic suits for those who have more money), and by manipulating their avatars. Their avatars can complete quests, collect magical items (which they put into their “inventories”), teleport from one location to another, explore different worlds, and so on. It’s a pretty engaging book with detailed and believable world-building.

One day the OASIS developer, Halliday, dies. He is enormously rich and with no heir. Who will he give the money to? He decides to create the ultimate game and award the prize to the first person who can find the hidden easter egg. This sets off a ton of adventures with our main protagonist, Wade, who learns everything he can about Halliday’s world – the video games he played, movies he watched, and other 1980s trivia from Halliday’s youth.

I’m only half way through the book, but I’m guessing that eventually Wade will win this game (or else team up with his cybercrush Ardemis and win it). But that’s sort of beside the point.

What is my point? Both Halliday, the brilliant video game creator, and Wade, the game-playing protagonist absorbed in Halliday’s video game and world lore, love what they do. Wade is engrossed in Hallidsay’s 80’s pop culture, video games, and life in the OASIS. It pulls him in fully and absorbs all of his attention. He loves video games and plays for the sake of the game.

Let me circle back to the mountain of documentation and other tasks. On the one hand, I could view this as a kind of endless list of to-do’s, the only really interesting thing being checking off the boxes beside the tasks. I’m not sure I can ever fully change my attitude to embrace the same zeal and drive that Halliday and Wade have with video games, but I am convinced that this element of fun, of obsession and interest and full absorption, is what drives one toward total mastery and ultimately brilliant feats of accomplishment.

The problem is that one’s natural inclination doesn’t always align with profitable outcomes. For example, Wade’s mastery of 1980s video games and life in the OASIS doesn’t do much for him financially except qualify him to work as a tech support agent at a company called Helpful Help Desk.

This past week I sort of let go of my goals and tried to get absorbed in my natural interests. You know what I ended up doing? Jekyll stuff. I refactored the Jekyll doc theme at my work to support translation, figured out how to drive a glossary and tooltips from a YAML file (across multiple languages), came up with a nifty technique for handling bookmark links from the sidebar navigation, integrated Bootstrap nav tabs into the UI, explored how other theme developers implemented breadrumbs, interacted a bit on the Jekyll talk forum about templates, and more.

If I wanted to put my mind to it, I could become more adept and skillful in creating documentation themes out of Jekyll. But as my wife reminds me, when you compare building this kind of knowledge against knowledge about Java, Android, or other programming languages, there’s a clear winner about which one has greater payoff. And that’s the dilemma for me. It is easy to get wrapped up a publishing tool, but developing content about technical issues developers face is the real payoff from a career standpoint. One day you could change jobs to a company that uses a different approach for authoring, and then all that tool knowledge would be wasted (most likely in the same way that learning Android would be irrelevant if you suddenly joined Apple).

I’m still in flux. I can develop a mediocre knowledge of developer tech, or I can go deeper with Jekyll, or maybe explore something else altogether, like web publishing in general. The web (not too unlike the OASIS) is the larger funnel for most of my activities. Regardless of the direction, all my activities seem to converge in building out my technical skills, which no doubt helps in any technical writing endeavor.

Other Stuff