Author Archives: Dan Littman

Maturing Your Information Development Processes – 5 April 2018 [Meeting]

What makes an industry leader in the area of information development? What practices are critical to the department’s success and predictors of the quality of content produced?

For over 20 years, Comtech and the Center for Information Development Management (CIDM) have partnered with leading information development organizations to assess and monitor the characteristics that define process maturity in the creation of technical content.

Tools, technology, and user expectations continue to evolve the content we produce. Similarly, the processes followed while creating that content should also adapt.

To respond to changing demands, we must leave behind our old concepts of information development management and adopt new definitions of process maturity.

Based on continuing conversations with leading information development organizations, this presentation examines key performance indicators for 10 characteristics that define mature organizations in today’s market.

About Our Speaker

Dawn StevensDawn Stevens is the president of Comtech Services and Director of CIDM. With 28 years of experience, including 17 years at Comtech, Dawn has practical experience in virtually every role within a documentation and training department, including project management, instructional design, writing, editing, and multimedia programming. With both engineering and technical communication degrees, Dawn combines a solid technical foundation with strong writing and design skills to identify and remove the challenges her clients face in producing usable, technical information and training.

Meeting Logistics

Date: Thursday, 5 April 2018.

Meeting Recap

by Dan Littman

Structured-content methodologies, in particular DITA, have spread inexorably through the tech–comm world over recent decades. At the EBSTC’s April 5 get-together we heard from a street–smart DITA consultant about how the methodology affects not just technical documentation, but also how companies organize themselves and operate. Our guest speaker was Dawn Stevens, who last year took over at Comtech Services, the influential Denver–based DITA consultancy started by JoAnn Hackos.

Dawn prefaced her presentation with some remarks about the changing purpose of writing technical documentation. Structured authoring, and in particular DITA, emerged as a way to “future–proof” information so it can be easily adapted for new communication technologies. Dawn points out that DITA comes with a taxonomy attached that makes it ideal for incorporation into the latest communication technology: artificial intelligence information systems. The consequence is that the technical books and procedural guides of yore are being eclipsed by small chunks of self–assembling information—a necessary transition as the audience for information moves from humans to machines.

We technical communicators have to adapt to what that demands, which includes:

  • new tools, such as XML and CMSes
  • new platforms, such as dynamic and social media, and of course mobile devices
  • new technologies, such as video and augmented reality
  • new responsibilities, such as planning taxonomies and designing for user experience

All those changes have knock-on effects for people who use our information, which in turn requires us to adapt in other ways as well. As an example, Dawn cites studies that show people average a 60 percent retention rate for what we read on paper, but only 18 percent for information on a smartphone screen—which drives an increasingly “just–in–time” approach to seeking information.

Well, after making those points, Dawn didn’t talk so much about DITA itself, concentrating more on how organizations change to make room for DITA. Her presentation, entitled “Maturing Process Maturity” (see her card deck here), zeroed in on 10 key business considerations and practices that determine whether organizations can reap the benefits of structured authoring. In no particular order, the 10 factors are:

  • Organizational structure
  • Hiring and training
  • Collaboration
  • User awareness
  • Budgeting
  • Planning
  • Estimating, scheduling and tracking
  • Information design
  • Quality assurance
  • Change management

None of these practices are really new (except perhaps information design), but the challenges they present and the ways they’re executed are changing. Some requirements have clearly become easier to meet due simply to better technology. In the case of collaboration, for example, everything from email and network servers to video–conferencing and content–management systems allow tech–comm departments to work fluidly together. And when it comes to QA, there are tools available that incorporate the tech-comm department’s style guide and keep writers attuned to established procedures.

Even so, Dawn has concluded that most tech-comm departments still perform poorly on the 19th–century–sounding requirement to estimate, schedule and track their work. Budgeting also trips up its share of sincere efforts. And she finds that organizations whose functioning on many of the 10 factors is at mediocre to middling levels (on her informal five-level scale) are doomed to run aground on any attempt at deploying DITA in their operations.

At our next meeting, on Thursday May 3, EBSTC chapter president Gale Naylor will describe her journey from volunteer on an open-source project to a paid career gig at a major Silicon Valley company. It’s an interesting story, and it should be especially useful to anyone trying to find a niche in the tech–writing world. Mark your calendar for an evening at our new meeting room in the San Ramon Marriott’s Bishop Grill.

How to thrive as a technical writer on a scrum team – 1 March 2018 [Meeting]

A common misconception about scrum is that it doesn’t value documentation. This presentation will cover the principles of scrum, providing an explanation of how this misconception occurred and how you can demonstrate the value that you bring to the team. We will also explore some skills, many of which you might already have, that will help you thrive as a technical writer in a scrum environment.

About Our Speaker

Shari Clare has traveled a winding path in her journey through scrum. Her first career was as an Elementary School Special Education teacher. She retrained to be a Tech Writer in 1993, and has worked at about a dozen high tech companies throughout Silicon Valley. She began learning about the scrum/agile in 2006 from Jeff McKenna, a founder of scrum, then became a Certified Scrum Master in 2010. She has worked with scrum teams while at previous jobs at Voltage/HP/HPE. She had been working for about year without the benefit of scrum at Zoom, and recently left to join Telenav, in large part to work at a company using a scrum environment.

View the Slides

Meeting Logistics

Date: Thursday, 1 March 2018

Meeting Recap

by Dan Littman

If you’ve been anywhere near the software world in the last decade or so, you’ve certainly heard about the overlapping development methodologies variously known by Agile, scrum and other terms. Our presenter at the March 1 chapter meeting, Shari Clare, recently came off a gig where she was the sole tech–writer supporting a crew of 300 software developers. She says that to survive there, she snuck in some unsanctioned Agile practices just to get a handle on the workload.

Shari gave us a short history of software development methodologies and a thorough grounding in what Agile and scrum bring to the table.

Briefly, part of what defines Agile is that development tasks are broken down into small actionable chunks and attacked by small teams in bursts called “sprints,” which run just a week or two. Pieces of the design specification are produced collaboratively and sequentially—instead of in the parallel and uncoordinated way of old—and the engineering–complete goal for each sprint is highly defined. That forces the design specification into the open, keeps the team focused on specific modules that can be nailed down in predictable steps, and allows progress to be clearly measured and sticking points quickly identified.

But the Agile methodology goes well beyond normal engineering routines—and normal office routines, for that matter—in asking team members to adopt a specific mindset and follow a set of group–dynamics practices. The Agile Manifesto, first released in 2001, explicitly favors individuals and their interactions over processes and tools, and favors customer collaboration over contract negotiations.

In addition to attending daily standup “scrum” meetings facilitated by a “scrum master,” team members participate in “ceremonies” to mark certain milestones, such as sprint planning, the sprint review (to demo software progress), and the sprint retrospective (to analyze successes and failures). Product owners define the development goals in terms of “stories” that explain what the end–user will get from the software. Then, in scrum meetings, team members define their daily tasks in terms that fulfill the vision of the story. Each team member describes what his or her next piece of the project is, why it is needed, and what constitutes completing it successfully. And members pledge to the team to fulfill the commitments they’ve made for themselves.

You’re probably wondering by now what all this has to do with tech–writing. Well, consider this: At her recent position, Shari quickly emerged as the scrum master. She was shocked at first, but she soon understood that being intimately involved with the programming team yet not being a programmer gave her a perspective her team needed to see the big picture; she points out that a lifetime as a professional communicator didn’t hurt either.

Here are the Agile/scrum tasks and attitudes that Shari believes a tech–writer can—and should—take on for the project.

  • Attend all the scrum ceremonies for your team(s). Adopt the mindset and participate.
  • Use the daily standup meetings to keep abreast of what documentation demands are approaching.
  • Inject your documentation tasks into the stories that drive each sprint. Make sure that finishing docs is part of the definition of complete.
  • Keep documentation in sync with the development process. You’re as committed not to fall behind as the programmers are.
  • Help the product owner write the user stories.

One more point: True to its name, Agile isn’t standing still. A new formulation is emerging, called “Modern Agile,” that has four guiding principles:

  • Make People Awesome
  • Make Safety a Prerequisite (i.e., protect and support each other)
  • Experiment & Learn Rapidly
  • Deliver Value Continuously

Agile, in some form or another, is here to stay, so if you want to steer your tech–writing career toward high–paying software documentation, take the time to educate yourself in Agile and scrum before you go for job interviews.

Coming up: For all you DITA–using and DITA–curious tech-writers, at next month’s chapter meeting we’re slated to hear from Dawn Stevens. Dawn recently took the helm at Comtech Services, the influential Denver–based DITA consultancy started by JoAnn Hackos. Our new room in the San Ramon Marriott’s Bishop Grill is bigger and more modern than our previous digs. It’s also more expensive, which is another good reason to support the chapter by attending the April 5th meeting.

Adding Marketing to Your Writing Toolkit – 1 February 2018 [Meeting]

To those of us with a technical background, any kind of marketing work can seem like a dark art indeed. But technical writers have always been involved in white papers, spec sheets, and similar pieces. Even online help is being mined by marketers for its “SEO juice”. You’re probably already close to being able to add “Marketing” to your skill set. Come watch as Floyd Smith, published author and Director, Content Marketing at very technical startup NGINX, shows you how to stretch to new horizons.

About Our Speaker

Floyd Earl Smith is an experienced technical writer, marketer, and manager. His work background includes Apple, AltaVista, AOL – and that’s just the A’s! Published books include Programming the Intel 80386 Director, Content Marketing for NIGNX, a San Francisco-based tech startup.

Meeting Logistics

Date: Thursday, 1 February 2018.

Meeting Recap

Are tech-writing and marketing doomed to forever mix about as fluidly as, well, oil and water? If you were at the East Bay STC’s Feb. 1 dinner get-together, you heard a technical-marketing guru provide a more harmonious perspective.

Our presenter, Floyd Earl Smith, works at NGINX (pronounced “engine-x”) and bears the title Director of Content Marketing, which he comes to after gigs as a senior tech-writer at Apple, Google, Visa and AltaVista.

Floyd’s company sells highly technical software tools for running Internet services, so when sysadmins and web architects come looking for information about the NGINX product line, they need to see more than light patter and simplistic claims.

What they’re looking for is a deep understanding of how NGINX performs as a web server, load balancer, content cache, firewall, and performance monitor and analysis tool, among other critical pieces of Internet operations. That means NGINX can’t afford to silo the marketing information and technical information about its products. And Floyd suggests that tech-writers would do well to recognize that part of what we do supports marketing–whether we like it or not.

Floyd drilled down on this a bit by distinguishing the B2B (business-to-business) sales process from the more familiar B2C (business-to-consumer) marketing. In a B2B situation, as with marketing NGINX’s tools, a vendor generally has fewer potential buyers coming through the door but with higher potential dollar amounts, so it becomes more practical–and more important–to communicate with individual customers. And at NGINX, an important part of the communication is putting accurate, complete technical information on customer-facing pages, which potential customers use to vet marketing claims. But Floyd emphasized that making technical information available in the marketing or pre-sales stage of the process does not mean including marketing information in technical documents. In fact–tech-writers will like this–Floyd resists efforts at his company to modify technical documents for search-engine optimization purposes, because it interferes with the writers’ ability to write clearly and distorts the final product.

But he also points out that as tech-writers we have an obligation to understand how our companies’ marketing departments look at the technical sales process. To educate East Bay STC members on the sales process, Floyd’s presentation featured several versions of the “sales funnel,” a marketing view of the stages every deal passes through. Here’s one version of the funnel:

Floyd Earl Smith’s presentation, 2/1/18

You can flip through the whole presentation at this link.

Floyd summarized his philosophy as a tech-docs/marketing crossover for us in several concise guidelines:

  • Consistency in tech docs has better SEO results than modifying your docs to chase some mythical SEO keyword or phrase.
  • Putting technical documents on customer-facing pages is a simple, honest way to bump your page views and raise your visibility in search engines.
  • Companies need to operate with enlightened self-interest wherein marketing departments support tech-docs departments, because what we tech-writers produce is what clinches a technical sale and brings repeat customers.
  • Marketing departments in a technical environment should start with their tech-writers’ documents as the basis for marketing information–not the other way around.
  • Tech-writers should understand the usefulness of some marketing practices, such as telling readers why they need to know a particular bit of information.

What Floyd is promoting, in sum, is for marketing and tech-docs to incorporate the best of each others’ worldviews and practices. The result of doing so will be to make it easier for potential customers to buy in to your company’s product line.