Category Archives: STC NorthBay Blog

Our March 2011 Meeting: Optimizing Your Portfolio, with Andrew Davis

Andrew Davis, formerly principal of Synergistech Communications and now a recruiter for Content Rules (formerly Oak Hill Corporation), provided valuable insights (both live and remotely) at our March 2011 meeting. A true champion of the candidate, he reads a lot of job descriptions and resumes, and made clear that a great portfolio (and approach) is your best chance of landing a job in technical communications in the current environment (which, perhaps surprisingly, is becoming more and more favorable to the job seeker).

You can’t just have a resume anymore; you need hard evidence to back up what is on it:

  • Provide proof that you understand your audience, really know your tools, and can organize, write and deliver.
  • Have you mastered the three types of software documentation content (procedural, conceptual, reference)?
  • Have you mastered the three basic delivery types (linear prose, task-based help, instruction)?
  • Have you developed concrete doc plans?
  • Have you demonstrated a master of doc organization (TOC, concepts, procedures, reference, glossary, and even the index?)

Well, have you?

So what sells in the current market?

  • Clean, friendly prose with the end user clearly in mind
  • Illustrations, useful screen shots
  • Code examples
  • Complete instructions
  • Use cases and implementation scenarios
  • Troubleshooting

The audiences for each of the above are different, but the aspiring applicant who can demonstrate mastery of most of the above stands the best chance of success.

And when you are on the spot in front of your prospective employer, what wins?

  • An effective presentation, with information that is accessible, relevant, and in a meaningful context: what were the conditions, constraints, and strengths and weaknesses (yes, those) in how you succeeded — or not?
  • How did you approach similar challenges?
  • What did you deliver and why?
  • What did you learn?
  • How did you succeed in the end?
  • What was your role in development?
  • What were all the circumstances you encountered and how did you deal with them?
  • What would you do differently next time?

In short, be the best narrator you can, and leave nothing to chance.

So how does one deliver success stories these days? Many use the ubiquitous and affordable LinkedIn (which also hosts a “Creative Portfolio Display” section). Or develop a private website in which to hang your best work with a narrative. For the transfer of large files to your prospective employer, use box.net. Or use private directories (password protected, of course) and even (duh) email (for files that are not too large).

But, you say, all my examples are proprietary? Well, if you don’t deliver something, employers will assume you are bluffing if you just say, “Sorry, I have great stuff — just can’t show it.”

Too bad for you.

So how do you deal with the sticky issue of proprietary information? Here are Andrew’s suggestions, in increasing order of difficulty:

  • Ask the prospective employer to sign a nondisclosure agreement (NDA). Companies ask others to do that all the time, so don’t be shy. It shows you are a mature negotiator as well as a respector of (eventually their) intellectual property rights.
  • Neuter the content. Do search and replace on a variety of key words.
  • Redact key sections, as Acrobat Pro allows (Acrobat Standard may do this too). However, even though you can black out words and lines, be sure to lock the file against further edits!
  • Ask your ex (or currrent) boss for permission. Your judgment call here.
  • Contact your current (or previous) legal department for permission. Your judgment call here.
  • Ask for the names, addresses, and SSANs or the reviewing parties. Your judgment call here. (Success stories would be interesting to hear.)

In the absence of success in any of the above, or even if you have no current examples of the types of documents you would like to write, you can always take a public-domain document or public-domain information and rewrite and reorganize it, demonstrating your clear command of information management. Demonstrate your command of a technical subject area, as well as of your understanding of your audience.

Finally, avoid the classic “I am such a quick study, just teach me anything I need to know and I will learn it.” Well, that does not work in the current environment. No employer wants to hire a liability, and your inexperience should not end up their problem. Hiring managers are terrified to make a wrong hiring decision, and will instinctively minimize their risk any way they can.

So demonstrate the following with concrete examples: initiative, motivation, a master of subject matter sufficient for the task, an ability to overcome gaps in information and other challenges.  Most of all, make it crystal clear that you will be a good investment.

It is as simple as that.

For additional information, don’t hesitate to contact Andrew at andrewd@contentrules.com. Your success and his are intertwined.

Our January 25, 2011 Meeting: “Write More, Write Less” with Joe Welinske

Joe Welinske has been a technical writer since 1984, and one of his first documents was a comic book. In four colors. For plumbers. To put in a hip pocket. Why make plumbers carry around a standard size tech doc to tell them how fit pipe when something much smaller would do? The manual was a hit, and an great illustration of the practicality tech doc writers often overlook when tasked with user assistance, or UA. (His website is www.writersua.com.)

Joe currently crafts user interfaces for iPhone apps and scripts YouTube videos to support other mobile apps, but he wisely counsels us to remember there is more to our trade than tools and technology. Having been recently in a hurricane in the Caribbean, he  showed examples of old-school journalistic style (on CNN’s website) that presented just the weather information he was curious about and in the correct order and proportion. Keep your key ideas up front, save the details for later, and do not overwrite so that you bury a good message in clutter — just simple, classic journalistic principles.

He cites Jakob Nielsen on good web design (see www.useit.com), and how readers do not approach web pages linearly. Here again, use the inverted pyramid approach from journalism school (you did take some journalism, right?), and lead with the conclusion if you want to be efficient and make your readers happy. Use bullets, meaningful subheads, one basic idea per paragraph, and toss unnecessary words. Some of us, like Dickens, may get paid by the word, but odds are that every unnecessary word is just a burden in your organization, from first draft through ongoing maintenance and costly localization.

Says Joe, “UA will become most effective when we spend twice as much time writing half as many words.”

Anyone wishing to polish up UA skills would do well to consider the Conference for Software User Assistance, to be held March 13 through 16, 2011, in Long Beach, Calif. The conference focuses on “developing the best possible user experience for all types of software applications through well-designed interfaces and helpful and accessible support information.”  In short, “Better UX through Better UA.” For details, see www.writersua.com/conference.

January 22, 2011: Annual Berkeley Chapter Party and Touchstone Awards

Join us to relax with fellow communicators, enjoy a buffet dinner, and celebrate excellence in the profession.

Every year Touchstone, the Northern California Technical Communication Competition, receives many fine entries. We send the best ones to the STC International Summit Awards competitions. We will announce this year’s winners and display their entries throughout the evening.

During the evening we will also recognize and honor competition judges and Berkeley chapter volunteers for their contributions to the chapter and the profession.

Our yearly raffle: Wow, do we have some great items for our raffle this year! Thanks to the generosity and support from these wonderful vendors in our professional community:

* Adobe is providing a copy of Technical Communication Suite 3
* Author-it is providing a full user license to Author-it
* ComponentOne is providing a license for Doc-To-Help Enterprise
* MadCap Software is providing a copy of Flare V6
For menu and registration details, please go to http://www.stc-berkeley.org/MonthlyMeeting/january2011_annual_party/meeting_details.shtml.

Our October 2010 Meeting: Publishing PDFs from DITA

At our last meeting, Scott Prentice, chapter webmaster and president of Leximation, Inc., presented a concise summary of the motivations and issues involved in using the Darwin Information Typing Architecture to produce PDFs. Why use DITA at all? By using XML to author in a topic-oriented structure, DITA lets you rearrange topics and reuse them easily, depending on the deliverables (paper? PDA? online help?) you want from the same source material.

Isn’t this a wonderful thing? Yes, it can certainly be, depending on the nature and size of the enterprise and the amount and different types of content required–but it is not for everyone, and you had better choose your approach carefully from the start.

The great value that Scott provided in our online session was in detailing the various options. How much “manual” control to do you need (and have the technical resources to support)? How much built-in support do you need (and have the budget for)? What is the volume of your output and projection for future need, and how many “seats” do you need licenses for? These are just a few of the questions you must ask before heading down the DITA direction, because what looks like a simpler, more affordable approach at first could turn out to be an expensive, painful trap.

For a concise listing of the products, prices, and particulars of a variety of commercial DITA applications, you can’t do much better than review the brief summary of DITA issues that Scott has provided. Read it and be wise.

Our August 2010 Meeting: 101 Ways to Impress With Your Writing and Speaking

We in the technical documentation community are skilled writers and speakers. True. And we never need to revisit basic principles, and never ever get contentious over language. Not so true. This makes life fun.

At our August 2010 meeting, Arlene Miller, author of The Best Little Grammar Book Ever!, came with a short list of grammar questions, and not surprisingly there was a spirited discussion about the answers. Despite what we have learned in school and over the years, there is always room for analyzing the best way to say something — and sometimes for deciding whether to say it at all.

In keeping with the spirit of the evening, Arlene will be monitoring our new Grammar forum. Try this resource when you bump into a language challenge you would like to resolve, or just want to add expertise to the conversation.

Our July 2010 Meeting: A Tour of Virtual Worlds and How They Impact Technical Communicators

In this online-only event, Mike Ziegenhagen shared his growing expertise–and most of all his enthusiasm–ror the expanding sector of virtual world applications. Many are by now aware of Second Life, but Mike documented an application from Forterra Systems called OLIVE ™, an “online interactive virtual environment” that offers the security sorely lacking in the standard, free version of Second Life (OLIVE can be seen as “Second Life in business suit”). His experience with the team was also a great opportunity to work with both artists and actors, to achieve the best possible renderings and life-like actions of the avatars. Verisimilitude is more and more critical to success. Mike also gave a brief tour of Blue Mars, a 3D social networking application, based on high-definition game technology, that is definitely worth exploring.

There are additional applications for hosting secure virtual meetings: Venuegen can be “rented” for under $100/mo. for ten people or so, and 3DXplorer offers an enterprise beta version. Both are browser based. Also, Second Life Work offers an application-based approach for those willing to buy.

Why bother? It turns out that business are seeing the advantages to hosting so-called hybrid events and conferences. Participants who want to meet in meatspace continue to do so, while those distributed around the world appreciate the advantages of entering the virtual world. Indeed, perpetual virtual environments are turning out to be profit centers. Not only that, but they can be really fun (as long as you don’t get lost in layers of consciousness, Inception-style, so to speak. It is actually not all that hard to get lost. But fortune favors the brave and the curious. With increasing bandwidth and video processing power for less and less money, it it not inconceivable to see virtual meeting places become more and more common. They can be used to unite family members, and they provide unique opportunities for training. STC is rumored to have a group (more detail to be provided when it is available), and you can always check out NPR’s Science Friday Second Life.

Next steps?

  • Do some research.
  • Explore some sites.
  • Download Second Life viewer and take if for a ride.
  • Get a good headset.
  • Have some fun.
  • The NorthBay Chapter is looking forward to playing around with this new medium, so stay tuned and let us know if you want to test the virtual waters. It is almost as if the spirit of the early days of computing were back again.

    LavaCon 2010: Manage Your Online Brand (and support your local chapter!)

    OK, you’re on Facebook and maybe Twitter. Now what?

    Join other technical communicators at the LavaCon Conference on Digital Media and Content Strategies, Sept. 29–Oct. 2 in San Diego, CA and learn how to use social media to advance your tech comm career.

    First, read Jack Molisani’s cover article on the June Intercom magazine to see if social networking is for you: http://intercom.stc.org/

    Then go to http://lavacon.org to view the LavaCon program and register!

    Note: Register by August 6th using the referral code STCCANB to support the STC-NorthBay chapter and to receive $50 off your conference tuition!

    Introduction to DITA Workshop in Cupertino

    On August 7, 2010 at DeAnza College in Cupertino, the STC Silicon Valley chapter will have an “Introduction to DITA Workshop.” Some of the topics covered will be DITA concepts, tasks, references, DITA maps, tools and technologies (DITA Open Toolkit, XML Mind). There will also be hands-on examples so students will work on pieces they can include in their portfolios.

    Register before July 25, 2010 and pay only $60 for STC Members and Full-Time Students and $75 for Non-members. Register after July 25, 2010 and the fee goes up to $75 for STC Members and Full-Time Students and $100 for Non-members.

    To register visit http://stcsv.wufoo.com/forms/intro-to-dita-workshop/

    APIs and SDKs: Breaking into and Succeeding in a Specialty Market

    Seminar presented by API/SDK documentation expert Ed Marshall, Marshall Documentation Consulting in Boston.

    Cost: $195 per person (includes breakfast and lunch)
    When: Saturday, August 28, 2010, 8:30 a.m.–5:00 p.m.
    Where: Best Western Pony Soldier Inn, 9901 NE Sandy Blvd., Portland, OR

    Since the early 1990s, the demand for application programming interface (API) and software development kit (SDK) documentation for developers has grown rapidly and shows no signs of declining. At the same time, there’s a shortage of writers in this niche. They enjoy a steady income, higher hourly rates, and often the luxury of telecommuting.

    Contrary to some perceptions, API/SDK writers are typically not computer programmers. They’re technical writers who are detail oriented, who know how to glean information for documentation by reading developers’ code and communicating well with developers. Although having familiarity with one or more programming languages is important, technical writers can leverage skills they already have to add value to API/SDK documentation, such as the ability to organize information, recognizing where important gaps in the content exist, and providing consistency in content and use of terms.

    How do you enter and succeed in this market? Join Ed Marshall, a nationally recognized expert in API/SDK writing, for an introduction to this world of writing documentation for software developers on Saturday, August 28. During this all-day, hands-on workshop, you will learn:

    • What APIs and SDKs are and the similarities and differences between them.
    • Who uses APIs and SDKs and why.
    • The benefits and drawbacks of API/SDK writing.
    • How to gather information, primarily by reading the software code. For example, which files do you read? Which programming keywords are important?
    • What information you can get from the source code and what to look for. What information you can’t get from reading the source code.
    • Hands-on exercises using Doxygen and Javadoc to generate typical online documentation from a set of C and Java source code files.
    • The skills you need to succeed, including common programming concepts, software applications used for creating these documents, and tips for adding value based on your technical knowledge.
    • Where to find training.

    Ed will also show examples of typical API/SDK documents and demonstrate the software tools used to generate documentation from the developers’ source code. He will allocate ample time for participants to practice with these tools. Laptops are needed to complete the hands-on exercises. All the software needed will be provided by the instructor for installing on your laptop.

    About the Instructor

    Ed Marshall is an independent technical writing consultant and sole proprietor of Marshall Documentation Consulting, with more than 22 years of experience. He specializes in APIs/SDKs (application programming interfaces/software development kits), Web services products, and other types of documentation aimed at developers. Throughout his career, Ed has developed expertise in using tools to “let the computer do the work,” such as advanced tools for editing files, comparing files, and searching and replacing text in files.

    Ed is a popular speaker at a variety of professional development conferences, locally and nationwide. His previous appearances include events sponsored by the Society for Technical Communication (STC), WritersUA, and DocTrain.

    For more details and to register, see www.tabbycatco.coml.

    Our June 2010 Meeting: Creating a Knowledge Base using MadCap Flare and Madcap Feedback Server

    Wendy Bidwell had long planned to present at our chapter but was now in Florida.  Would she accept our offer to present remotely using Acrobat Connect? Indeed, she took the plunge and all went very well, becoming our first formal telepresenter.  The commute and parking were much easier, despite the late hours for her.

    Her theme: How to use MadCap Flare in conjunction with MadCap Feedback Server to manage data in association with an online help project–improving communication among writers, customers, and employees.  So-called “out-of-the-box” applications just weren’t doing it, but Flare provided a great way to manage a knowledge base, while making it easy to export content to a variety of target output formats. Combining MadCap Flare with a Feedback Server to create a company knowledge base provides improved, interactive communication among writers, customers, and employees.

    Users can add comments and rate topics, and writers can analyze user searches. This provides the same kind of valuable information one would have to obtain from talking to customers and support personnel and conducting usability studies.

    For detailed instructions on installing and configuring MadCap Flare and MadCap Feedback Server in this context, see Wendy’s document. Other servers are also supported.