Newsletter of the East Bay Chapter of STC
Supporting technical communication in the
San Francisco Bay Area since 1962
Return to EBSTC Home Page
First Quarter 2017 Issue
Time to Celebrate!  ****  Excursion to the Bay Model June 3, 2017
Dinner Meeting Recaps
Editor as Collaborator  ****  Creating User Docs in an Agile World  ****  Minimalist Writing for Maximum Communication
Greetings from your new president! If you're reading the email version of our newsletter, I hope you'll take a moment to hop over to www.ebstc.org and admire our beautiful new website! We are LIVE on WordPress, and it's all thanks to our stellar WordPress migration team headed by Jane Olivera, with Joe Humbert, technology insight from Liz Fraley, and driven to completion by past-president Liz Miller. Kudos to the team for completing this major project, and please check out our Friendly new website!
I'm also proud to announce that Jane Wilson was recently elected STC's Vice President. We're excited to be a part of her journey the presidency of our national Society. Also, at this year's Summit, STC will recognize Patrick Lufkin as a Fellow and Joe Humbert as an Associate Fellow. These recognitions are well deserved; I hope you'll join me in congratulating Jane, Patrick and Joe!
(Speaking of the STC Summit, if you're planning to attend this year, won't you consider being on our June recap panel? We'll be sharing Summit experiences and would love your insights. No preparation required! Drop us a line!)
I'm also pleased to announce that Liz Fraley is the recipient of the EBSTC 2016 Technology Insight Award (again)! Liz has been the linchpin in our efforts to move EBSTC.org to WordPress, and we very much appreciate her knowledge and patience.
As beautiful as our new website is, we're still adding content. In fact, that content could be from you! Want to be involved? Contact us!
EBSTC and the Berkeley chapter are planning a trip to the Bay Model on Saturday, June 3. Contact us if you are interested in joining us on this excursion. Patrick Lufkin, who is arranging the excursion, explains what is the Bay Model and its significance to technical communicators.
The Bay Model is a huge--several acres--working model of San Francisco Bay and the Delta, operated by the Corps of Engineers. Once a working scientific research tool, it is now primarily an educational site. It offers a unique experience that very few people in the Bay Area know anything about. We all live in the Bay Area and deal with the state's water issues, and it behooves us to know more about them.
The Bay Model is also interesting from a technical communication perspective. In maintaining the Model, the Corps of Engineers as taken what was once a scientific instrument, and turned it into a technical communication tool. It marshals a full range of technical communication techniques to deliver its content, telling the story of the Bay, the Delta, and California's unique history and situation with respect to water. To do so, it uses dioramas, posters, signage, and more. There is a small theatre and a movie. There is an audio station where information is available via telephone style head phones. And of course, there is the huge Bay Model itself, a fully labeled and detailed working model--pumps move the tides up and down during the day--of the Bay and delta. You can circumnavigate the Bay, walk over parts of it on bridges, and become aware of parts of it most of us have never visited. There is also a room dedicated to ship building on the Bay during the "Rosie the Riveter" period of WWII.
The Bay Model is located on a main road just north of Sausalito and both the Model and parking are free. For more information, visit the Bay Model website.
Patrick Lufkin has experience in computer documentation, newsletter production, and public relations. He reads widely in science, history, and current affairs, as well as on writing and editing. He chairs the Gordon Scholarship for Technical Communication and co-chairs the Northern California Technical Communication competition.
The Editor as Collaborator - Communication Makes the Difference
From years of experience, Lori Meyer can say with confidence that when it comes to technical editing, a communicative relationship and empathy with the author is the key ingredient to a productive collaboration. When there is open communication and good teamwork, an editor's value can change from the perception of a grumpy Comma Cop to a valued resource and key member of the team
A good relationship begins with the editor's attitude: Do you get frustrated when writing is unclear, incomplete or poorly structured? Do you blame the client for schedule pressures or not recognizing the need for a heavier edit than a quick copyedit. Do you prefer to stay buried in your work rather than building the bonds of face-to-face connections? If so, others' perceptions of you and your value as an editor will likely reduce opportunities and the quality of written content in your group.
According to Lori, communication is the secret sauce that makes the difference, and she offered several practical tips for forming a collaborative relationship with the writers whose content you are editing:
- Rather than correct, collaborate with the author. Take a teamwork approach in making revisions.
- Build a friendly relationship, agree on edit level and other expectations, give the author a heads up on your editorial approach.
- Avoid harsh or non-helpful feedback such a big question mark or "Awkward" or "No!" in the margin. Coach on rewording by noting "Consider this rewrite suggestion..."
- Compliment examples of good writing and encourage more of the same.
- Resist being judgemental. Have an open mind about the author's environment, the project backstory, English language skills and peer community (Academics? Petroleum engineers? Geologists? Novelists? Software gurus?)
- Keep a scratchpad nearby for quietly and harmlessly venting editorial frustrations: "There is no such verb as SOLUTIONING!!"
If you really want to gain the respect and future opportunities that come from helping your colleagues or company avoid embarrassing content issues, dare to offer your educational services to the appropriate audience. A presentation to share the goals, edit levels, dictionaries and internal style guides behind an editor's work can build not only your reputation as an editor but that of all editors.
Creating User Document in an Agile World
In the February 2 dinner meeting, Jane Wilson presented, "Creating User Documentation in an Agile World." She spoke as a communicator working in Agile methodology. Agile was created by 17 guys at a ski lodge in 2001 as an alternative to the traditional method of document development known as waterfall. Waterfall follows linear steps from Customer Needs to Software Design to Implementation to Verification to Maintenance, in which each step is handed off from one group of developers to the next.
Agile takes a different tack, using teams that perform work iteratively, by breaking down a project into short, easy to accomplish tasks. An Agile team consists of a Product Owner (who represents the customer's needs), team members (who, in theory, can each accomplish any task), and a Scrum Master, (who manages the Team cycles and keeps development on track).
Agile teams work in short sessions, called sprints, usually two weeks, sometimes more, sometimes less. The team meets in daily stand up meetings where each team member reports on progress made and any blockers to progress. All the steps covered in the waterfall model are followed in each sprint, and at the end of the sprint, the team should have a shippable product. By having these short sprints, the team can discover developmental errors and correct for the next sprint. .
Through the Agile process of re-iteration, the time for a product to be actually shippable should be reduced, and development should progress efficiently. In traditional methods, an error may only be discovered at the end of the product development, and require going back to a previous step to correct it and repeat time consuming steps that have already been done.
In the original development of Agile methodology, no consideration was given to information development. As a result, technical communicators have had to develop their own ways of fitting in to Agile teams. This can vary greatly from company to company, and even from team to team. Unfortunately, because writers often cover multiple teams, they can end up as an "outsider" to the team. Some tips for improving this dynamic include making sure that technical writers participate in all Agile ceremonies -- scrum stand-up meetings, planning, and retrospectives. Teams have to be mindful of the tech writer's time and schedule so that the writer may fully participate in each scrum team. Writers also should take an active role in recording their work similarly to the rest of the team (in stories, on scrum boards, etc.). Finally, writers should strive to be active participants on their teams - learn about Agile, and speak up to improve the process.
Minimalist Writing for Maximum Communication
Bruce Poropat is a practitioner and advocate for converting dense legalese into language that people can understand the first time they read it. In technical writing, the minimalist approach is reminiscent of Plain Language (see the federal government's definition).
To the minimalist, it is the content's message that is the priority, not the prose. In Bruce's presentation on March 2, he first shared examples of minimalism in representational art, music and poetry, including a renowned example of minimalist fiction writing: "For sale: baby shoes never worn."
In the remainder of his presentation, Bruce made more than a few great points that stimulated lively interactions around the dinner table. Below are a few memorable moments:
- One slide featured a photograph of a shiny brown textured roll that somebody actually recognized as a deep fried Hostess Twinkie! This is how Bruce illustrates "word fat." He demonstrated through audience participation and incremental slide animations how easy it can be to trim an overly wordy sentence to its message essence.
- Technical writers are familiar with the concept -- if not Bruce's term -- "word soup," the verbose fluff and phrases that we would replace with one succinct word. Bruce shared a before-and-after list that included "manner in which" (way) and "demonstrated the presence of" (verified or showed). What does "engaging in agriculture" mean? Farming of course!
Even single words can hint at minimalism issues within content. Bruce is always on the alert for forms of to be (is, are, was, were, be, being, been), which are indicators of passive writing. Words in future tense (will or would) have no place when documenting a system's present condition or capability.
Last updated: Saturday, March 18, 2017