Category Archives: Meeting Archive

Meeting Announcement Archive

From Open Source Volunteer to Full-Time Tech Writer – 3 May 2018 [Meeting]

Open source software projects provide writers (and software engineers) opportunities to develop their skills, make meaningful contributions, and produce authentic work samples. These projects are almost always looking for people to help out, including writing documentation and testing. But how do you get noticed when the primary communication channel is a mailing list, and no one knows who you are? Learn how Gale Naylor leveraged her open-source experience to change careers and become a full-time technical writer at Facebook.

About Our Speaker

Gale NaylorGale Naylor, Facebook, was an aerospace engineer for 15 years, then taught herself Visual Basic and became a programmer/analyst. She started at Facebook in October 2016 as a contract Technical Writer and converted to a full-time employee position in March of 2017. She also has a master’s degree in Education and likes to design outdoor living spaces. She’s active in her local STC chapter and is currently Chapter President.

Meeting Logistics

Date: Thursday, 3 May 2018.

Meeting Recap

Many STC members work as tech writers, but some are still figuring out how to break in to the business. A few years ago the EBSTC’s current chapter president, Gale Naylor, wanted to transition from a career in education into a tech-writing position, so she came up with a clever, methodical and ultimately effective strategy for making the leap. The best thing about it, as Gale explained at the EBSTC’s chapter meeting on May 3, is that her strategy is open to all comers willing to devote some time and energy to the open-source community. And it helped her land a job as a tech writer at Facebook.

So many of the software tools and computer standards the world depends on are not proprietary and not owned by private companies. Instead, it’s all public, or open-source, and managed by committees of academics, government employees, people seconded from regular jobs, and full-on volunteers. The engineers who define XML, TCP/IP and JPG, for example, or the programmers who write the Firefox web browser and the Apache web server, do their work through public committees.

Committee members volunteer on open-source projects for all kinds of reasons: because they want to keep up on the latest developments; because they want to influence the direction of a particular technology; because they enjoy the prestige, camaraderie and recognition that comes from helping out; because they want to give something back to the community. And Gale figured out that you don’t have to be a veteran programmer or highly-trained engineer to make valuable contributions on open-source projects. (Although, full-disclosure, Gale does have an engineering background, with a bachelor’s degree in astronomy and experience as an aerospace engineer before going back to school to become a teacher.)

Gale started out by researching what was hot in the open-source world and finding what interested her. She settled on the Apache Taverna project, a set of APIs for defining experiment workflows, including those used for astronomical research, joined its mailing list, and learned everything she could about Taverna. And though she didn’t have the skills to write code for the project, she got noticed by developing diagrams that helped the coders keep the project organized. She also began helping a coder with limited English to write up documentation explaining his work. As she continued to make herself useful in similar ways, she accumulated an understanding of APIs, knowledge of essential programmer’s tools such as Markdown and Git, and familiarity with how programmers work. When Gale applied to Facebook, she went in with a reputation in the open-source community and the skills that Facebook needed for documenting its developer APIs.

The open-source community is always looking for volunteers, so if you’re ready to get involved, check out the links to open-source groups on page 19 of Gale’s presentation.

EBSTC get-togethers are always the first Thursday of the month. On June 7, we’ll hear the impressions of members just back from the STC Annual Conference in Orlando . Hope to see you there, at our new meeting room in the San Ramon Marriott’s Bishop Grill.

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.

What User Experience Is and Why Tech Writers Should Care – 4 January 2018 [Meeting]

Back in the day, tech writers were the vanguard of software usability; the way to make software easier to use was to write a better user manual. But then along came usability, and writers discovered that they could better serve their readers by helping engineers to make software easier to use. Writers also made their instructions more accessible by providing user assistance in the form of UI text, tooltips, and context-sensitive help.

Nowadays we hear less about usability and more about user experience. In fact, the Usability Professionals Association (UPA) recently changed its name to the User Experience Professionals Association (UXPA). How did this happen, and what does it mean for the future of our profession? What is the role of technical writing in this new universe?

About Our Speaker

Nicki L. Davis, Ph.D. wrote her first user manual in 1980 while studying for her Ph.D. in chemistry. She has worked as a technical writer for over 35 years and conducted her first usability test in 1992. Nicki has served the Berkeley chapter of STC as treasurer, secretary, and most recently as president. She holds the honorary rank of STC Associate Fellow.

Meeting Logistics

Date: Thursday, 5 JANUARY 2018.

Meeting Recap

Summary: As a 35-year tech comm vet, Nicki Davis knows a thing or two about how to help engineers improve their designs to enhance user experience. Her presentation on January 4 revealed how technical writers can contribute, and inspired more than a few nodding heads, war stories and chuckles. Read more…

HCI aka Human Computer InteractionHCI snip

EBSTC members, you really should have attended Nicki’s presentation in person to appreciate these best moments:

  • How a 6’ x 6’ minicomputer with 64k of RAM inspired this PhD candidate to became a technical writer as well as a chemist
  • OK/Cancel cartoons (Copyright © 2003-2010 Tom Chi / Kevin Cheng) illustrating the many challenges of an HCI pro and often, writers too
  • Nicki’s visible delight at her audience’s enthusiastic reception and related stories

Writing and HCI teams face common goals and challenges

While HCI folks are primarily focused on visual design and patterns within a graphical user interface, they share the writer’s goals to minimize wordy text, maintain a consistent vocabulary and deliver what users actually need. As fellow technical communicators, they too are champions of task and user analysis, usability testing and taking the end user’s perspective. But both groups also share the difficulty of getting respect, recognition and early access to make the most impact for a positive user experience.

We also share the challenge to influence developers, project managers and UI designers who don’t feel guilty saying, “They’ll learn!” when we point out poor design, often too late in the project. An especially galling point was Nicki’s observation that at one old-school company, learning a particularly difficult software interface  was considered a rite of passage for new team members.

Eyes rolled when Nicki presented common challenges faced by both writers and HCI staff:

  • Various Dilbert strips by Scott Adams (Dilbert © 2018, Andrews McMeel Syndication) in her presentation featuring Tina the Tech Writer
  • Measuring ROI by page count or words per day rather than fewer calls to technical support
  • “It’s too early for your feedback right now, just make it pretty.”
  • Last minute, token additions to project budgets to cover usability
  • Disrespect and rudeness when we point out a usability flaw
  • Short-sighted project managers, developers and designers who just don’t get usability
  • Content sourced from Marketing rather than the writing group
  • Organizational silos that separate HCI from writers

What can we writers do to impact user experience?

  • Seek out your company’s HCI group, which may be named UI, UX, or Human Factors
  • Learn how your company approaches usability
  • Seek ownership of customer-facing text (button and tool names, context sensitive help, dynamic user guidance)
  • Volunteer to perform design Verification and Validation tasks ahead of implementation
  • Advocate for usability testing by real users where the project team can witness their struggles

Ultimately, if you want to influence and improve the user experience of products produced by your company, you need to communicate internally to inform, educate and demonstrate how your core skills can contribute to project teams and end user satisfaction.

Meanwhile, enjoy Nicki’s presentation and its cartoon illustrations.