Editor's Note: Each year, after the STC Annual Conference, we publish recaps of the conference in Carolina Communique. Below are several articles that summarize events at the 2007 Technical Communication Summit, which was the 54th Annual Conference of the STC (Society of Technical Communication). It was held May 14th to 16th in Minneapolis, Minnesota. These articles describe the opening and closing meetings as well as educational sessions at the conference.

Recap of the Opening and Closing Sessions

by Linda Roberts, Carolina Chapter Senior Member

This past May, around 1,400 people attended the annual STC conference — or STC summit as it was called this year. Besides changing the name, the goal of the organizers was to reinvent the conference with more advanced content and topics.

The goal of providing better content showed in the superb opening and closing sessions. When Simon Singh, author and TV producer (who also holds a doctoral degree in particle physics from Cambridge University), said he was going to be speaking about producing his award-winning documentary on Fermat's Last Theorem, a math problem, many in the audience seemed skeptical. But fears were soon put to rest. Singh considers himself as a communicator and interested the audience in his discussion of hooking his audience and in editing. In the documentary, Singh changed the words a mathematician said from "prime numbers" to "whole numbers" so that he would not have to waste precious time explaining what prime numbers to his viewing audience. Not many in the audience saw and heard the change until Singh told us to look for the obvious spot where the speaker's words did not match his lips.

Singh's latest book is on the big bang. He says this book was inspired by a song by Katie Melua ("the UK version of Norah Jones," Singh says) titled "Nine Million Bicycles." The lyrics for part of the song are as follows:



Singh penned an article ("Katie Melua's Bad Science") in The Guardian about the inaccuracy of these lyrics. In this article, he offers his own set of lyrics for the song. They are as follows:



Singh then showed part of a television program on which both he and Melua appeared. During the show, Melua played an updated version of the song which included Singh's corrected lyrics. They certainly didn't sound as good as the original but they were scientifically accurate. Singh said that on the show that Melua said that she "should have known better" because in school she was a member of the astronomy club.

Ze Frank, part Web developer and part comedian, provided the closing session. After spending a few days listening and absorbing excellent presentations, it was nice to sit back and laugh at Frank's multi-media stream of consciousness session where he discussed how information was communicated on airline safety cards and through public signs.


Linda can be reached at Linda dot Roberts at sas dot com.

Using Sample Programs to Document APIs and SDKs

by Meredith Kinder, Managing Editor, Carolina Communiqué

This session, held on Tuesday, May 15, 2007, focused on the types of information that technical writers should include in developer's guides and reference manuals that are written for APIs (Application Program Interfaces) and SDKs (Software Development Kits). These documents' audiences are programmers who will use the APIs to further the product in some way, such as to hook it up to a third-party software.

Manuel Gordon presented information at this session that was based on his (unscientifically-proven, yet often observed) theory that programmers would rather read source code than page after page of how-to documentation. He urges us to give them what they want: concise online documentation that is linked to sample programs that programmers can put to immediate use.

Types of Sample Programs

Gordon told us what we already knew but didn’t want to admit: unlike us, programmers are not "word people," they are "code people." Thus, they want to know how to complete tasks, not why to complete them in certain ways. They want immediate information. They want concise information. They want us to write the code for them! We can give them what they want by providing them with sample programs that appear in four forms.

• Demo Programs are used in situations where you cannot give code away, so you present similar code to help the audience understand how to use it.
• Model Programs are helpful to programmers because they take the model program you give them and adapt it to meet their own requirements. Model programs are pieces of code that shows users how to do Task A, Task B, etc.
• Tutorials are for programmers who want to know "getting started" types of information. Tutorials are programs that explain or show one concept and then build another concept off of that one. They teach the basic concepts to someone who needs general knowledge. They are too simple to be realistic and are an extension of the documentation.
• Code Snippets often reside in a section named "Sample" in the developer's guide and are shown for each function. Each function uses a few lines of code to illustrate points. Using code snippets in documentation proves difficult because of the number of methods, functions, and properties in object-oriented style APIs.

Sample Programs Based on Use Cases

Gordon explained how to use "use cases" to determine what sample programs you readers will want. By outlining how users interact with a system to meet their goals, you can both better understand your user and determine the best types of programs to include in your documentation. The use case approach answers questions such as:

• What type of programmers will use your product?
• What development languages will they use?
• What purposes are they buying it for?
• What goals do they have and how will they interact with the product to achieve these goals?

After researching and defining use cases, you should make sure that a sample program is included for each use case in your documentation.

Miscellaneous

Other tidbits of information that Gordon shared include:

• Reference manuals should:
  • Be generated by a documentation generation program (DGP), which converts source code comments into reference documentation
  • Contain sample programs based on use cases
  • Integrate and hyperlink to the developer’s guide
• Developer's guides should be:
  • Goal-oriented rather than task-oriented
  • Built around the sample programs
  • Contain getting started info, such as tutorials, as well as the how-to material
  • Include code snippets
  • Organized around use cases
  • A source that references the reference manual
  • Free of repetition and embedded sample programs (keep sample programs online and link to them in the developer’s guide so you can update it online)

Materials from this presentation may be downloaded from http://www.stc.org/54thConf/sessions/sessionMaterials01.asp.

Online Help's Path into the Future

by Meredith Kinder, Managing Editor, Carolina Communiqué

Although Neil Perlin's presentation on Monday, May 14, 2007, was officially titled "Not Your Aunt's Online Help Anymore," the title didn’t accurately describe the depth of information he presented to us. So for this article, which summarizes his presentation, I took the liberty to rename it “Online Help’s Path into the Future.”

Perlin argued that new technologies include XML and Web 2.0 and old formats such as HTML help are fading. He urged documentation specialists to help determine or help define our company’s strategy, and define our strategy to be one that supports our company's strategy. He advocates for all documentation groups and professional to not be a group that sits in the corner and gets told what to do. If you’re quiet, then they'll forget you're there. Ways to reach out include:

• Show programmers and other content creators how to make their writing better and easier, not perfect. For example, show them how to use the grammar checker in Word, as well as the readability checker.
• Learn the language of business and think of your deliverables in terms of what they can contribute to finance, accounting, and strategic planning.
• Change your status from a cost center to a profit center. Ideas for how to do this include creating tiers of your material for sale (such as charging the highest price for customizable material, lowest price for bare-bones material), charge for hard copy material, and create reusable pieces (especially training materials).

Perlin sees an ever-increasing importance for standardizing and integrating the standards into your culture. Standards for templates, formats, and writing contribute to efficiency and consistency. One of the hardest parts of standardizing is not creating standards, it’s "enforcing" them. A few ways we can enforce standards is to:

• Sell people on how standards benefit them, not you. For example, if your content creators use inline formatting in Word rather than styles, tell them, "Rather than using inline formatting, which causes the document to have a zillion styles, how about I show you how to change formatting in about five mouse clicks? And when you do it in one place, the change carries through to other places in the document, saving you lots of time."
• Make standards easy to understand and use
• Train people on how to use the standards
• Make use of the standards mandatory

Other miscellaneous ideas:

• Start keeping project development statistics to help you predict future work. This will help you know how long it takes to do certain tasks, so you don't underestimate the time it takes, thus putting more pressure on yourself to get things done in a small amount of time.
• If your training budget doesn’t allow for as much training as you'd like, assign people to become the group’s expert in new technologies, methodologies, tools, etc., and run lunch-n-learn sessions. This also helps folks practice public speaking skills.

Materials from this presentation may be downloaded from http://www.stc.org/54thConf/sessions/sessionMaterials01.asp.

Meredith Kinder can be reached at meredith dot kinder at sas dot com.