Newsletter of the Society for Technical Communication, San Francisco Chapter
August/September 2009
| Newsletter of the Society for Technical Communication, San Francisco Chapter August/September 2009 |
The June 2009 San Francisco STC meeting was a gathering of experts, because everyone who attended brought their own expertise literally to this Roundtable Event. Meeting participants moved from table to table every 20 minutes to share experiences, thoughts, and tips on these three topics: Agile Development, Editing, and Content Management.
Susan Becker, an IBM writer documenting the Informix database product, led this discussion. Firms use Agile development (Agile) to create software products over a series of iterations. Agile uses a lot of buzzwords including waterfall, unit testing, iteration, and scrum. Susan believes that each company needs to define their Agile process based on how they define these words.
Adopting Agile isn’t easy; some studies show that 20% of firms that try Agile don’t adopt it. In trying to make the most of Agile, Susan asks herself, "How can I make this work for me?"
Susan’s challenge is that at IBM, iterations can be two, four, or six weeks long. Because the Agile methodology requires that she always be thinking and writing fast to produce documentation in small chunks, she finds there's no time for ideas about how to document the finished product. Ideally Susan would have an Agile task called "think,” as well as a more sustainable pace.
There's a tension between what Marketing and Product Management want, and what some scrum teams agree to deliver. Every project has to make a detailed design, but it always changes.
When writing in an Agile environment, the downside for writers is that some documentation is discarded or changed over time. However, the upside for firms is that writers are an effective front-line resource for product testing and feature development.
CA Wily Technology, where I am a Senior Technical Writer, does software development using a combined Agile and waterfall approach. At Wily, large features that can't be built in a single six-week iteration are developed in chunks over a series of iterations. Developers code for the first three weeks, then send the partial or completed feature to QA for testing, QA tests the feature during the second three weeks of the iteration while developers fix bugs and prepare for the next iteration. Writers try to keep up with developers, typically providing development-approved content to QA at iteration end or one iteration later. When the development iterations are completed, Alpha and Beta periods are used for product and documentation clean up, bug fixing, and customer evaluations. When the product and doc are fully approved by QA, they are released for general availability.
Richard Mateosian, Berkeley STC Chapter President, feels that the methodology of design, code, test, ship, then maintain was the ideal software development process.
Susan is currently documenting an Informix open source product, and her team has lots of customer interaction. Wren finds that customer input is valuable, but hard to get.
Marie McElravy led this topic first by describing her favorite references: The Gregg Reference Manual by William Sabin, Developing Quality Technical Information by Gretchen Hargis, and Elements of Style by Strunk and White. Her fave dictionaries? The Miriam Webster Collegiate and online Oxford.
Marie's concerns are quality, clarity, and organization. Her advice to writers is to:
In today's market, editors are a luxury, and even peer edits are not a given. Due to writers being slammed, peer edits are rare. Even technical reviews are let go due to schedule crunch.
When doing peer edits, it's helpful to ask yourself, “Would a person in India or Europe understand this?"
If you have to self edit, let your content sit for a day or two before editing. If you only have an hour, check out the helpful editing checklists in Technical Editing by Judith Tarutz.
When writing for a corporation, having a style guide ranges from being helpful to essential. Having a corporate glossary is helpful, but it can be hard to get decision makers in all the functional areas to agree on term definitions. The Microsoft and Sun style guides are especially good for acronyms.
In this topic led by Gilbert Gonzales, the San Francisco STC Chapter President, the participants' experience ranged widely.
I worked on a successful pilot project implementing Documentum at a biotech firm.
Richard Mateosian worked as a writer for Documentum, a content management system provider. At the time Richard worked there, Documentum kept track of doc versions and had rudimentary workflow. It provided for topic management, digital rights, and supported web content management and various graphics formats.
One writer has a goal to work for a firm that uses XML for writing topic content. Her firm currently uses Frame to generate PDF and HTML. Her writer colleagues work in silos, share content, and duplicate efforts. Their current problems are a growing content set and handling localization.
Gilbert worked at Symantec, where writers used XMetal to generate XML topics on the fly (quickly, not an insect or a zipper!), that were then pulled into books. Gilbert's biggest problem with XMetal occurred when he wanted to write a new topic. He'd do a search in the content management system to see if anything similar or helpful had already been written, and would find hundreds of topics. The use of more and better meta tags would have solved his problem of overwhelming and unhelpful content management system search results.
Wren Withers, Berkley STC Chapter member