What’s Shakin’ in Tech Comm?

Andrew’s May 18, 2016, presentation What’s Shakin’ in Tech Comm? provided an up-to-date survey of what you need to do to enter and stay in the field. This meeting was summarized by Doug Bothwell.

A major theme of tonight’s presentation was The Present vs. The Past (that is, before the tech crash starting in 2000). Andrew made the following points:

  • It’s much harder to get into the field now. There are far fewer entry-level jobs. Most people now come into tech writing with a strong background in a technical field such as software engineering. Tech Pubs managers have much less say over budgets or staffing. Writers are now hired by committee, and one No vote is enough for you to not get the job.
  • Non-technical writers are easiest to hire offshore. Venture Capitalists have told Andrew that their preferred market for technical writers is India; they only hire locally if they can’t find the candidates they need overseas.
  • Teach thyself. Don’t count on on-the-job training. You need to have the skills employers BEFORE they hire you. Mentors and on-the-job training opportunities are much more limited than previously. There are lots of online resources for learning in-demand skills and technologies. You can also get trial downloads of popular authoring tools. “Army-of-one” types, people who can handle all aspects of creating a help system or deliverable, are very much in demand.
  • Get technical–the more technical you are, the better. A degree is mandatory, preferably in a technical field. Know the technology, the audience, and the tools. Once you’re on the job, you’ll need to learn the technologies you’ll be documenting yourself as much as possible; you can’t lean on Subject Matter Experts as much anymore.
  • Online help is the standard format for documentation now; PDFs are passé. Online help is often embedded in the software, which can make it hard to provide writing samples.
  • Open source organizations are leading the pack for software development in terms of innovation. There are many volunteer opportunities for writers looking to contribute to open-source projects. When documenting a particular project or library, one primary goal is to write a good overview and introduction that provides a short TTFHW (Time To First Hello World). Try to write something that gets the user hooked in 10 minutes or less.
  • In-demand skills include:
    • MadCap Flare.
    • FrameMaker, WebWorks, and RoboHelp are nothing to boast about.
    • Flare has supplanted FrameMaker, and there’s no excuse for not knowing Flare. XML authoring tools such as oXygen and XMetal. Multinationals and wanna-be multinationals are increasingly going to DITA or some other XML-based formatting.
    • Markdown format: ASCII text with very limited formatting. This is very easy to learn and widely used. There’s no excuse for not knowing it.
    • Content Component Management Systems are commonly used in the industry, but there’s no dominant player (yet).
  • Site generators such as Jekyll, Readme.io, and Swagger. Employers will be impressed if you can talk about these.
  • Fully offsite jobs are increasingly rare. Employers want you to be onsite until they trust you.
  • One piece of good news is that there aren’t as many people coming into the field as previously. Many of today’s would-be tech writers are techies who want to transition into something else.
  • Consulting can be more profitable than permanent positions, but are also more lonely and high-risk. You can easily go down the wrong path and specialize in something that becomes obsolete. In a permanent job, you have more opportunities to shape-shift and prove your versatility.

Q-and-A Highlights

“What about medical/biotech writing?”
Andrew doesn’t work much in this area, but said that you can make very good money, IF you have the right education, background, and connections. There’s a lot of work for writers who specialize in an in-demand niche. Most medical writing is contract work. A good resource to consult is the American Medical Writers Association.

“How do I get technical and keep myself marketable?”
Get into the in-demand areas such as security or open source. Work your LinkedIn network for people in those fields. Look for volunteer work to write in a hot field. Offer to write, organize, and contribute whatever skills and talents you can offer. Get the trust of someone who appreciates what you can provide. The ultimate goal in open-source work is to become a “committer”–someone who can commit changes into the official Github repository for a particular project. Not many have this status, but the ones who do have great status. Don’t try to to do this with an old-school, non-open-source, enterprise product. Recruiters are now looking on Github as well as LinkedIn for good writers.

“If I’m working in a proprietary field, how can I develop content that can be viewed publicly?”
Try to come up with a few chapters, such as reference or concept chapters, and “neutralize” the content. Get permission from someone in your organization to include it in a portfolio. Make your portfolio available online. Include an introduction that describes the context, the tools you used, and how you wrote it. There’s more advice on Andrew’s website.

“How do I avoid getting sideswiped in my career?”
Andrew told the story of a friend of his at a large, well-known software company. He was very comfortable: his job was stable, he liked his job, he thought he was safe…and then, suddenly, he wasn’t and got laid off. He’d gone too far in the manager space and had no real writing samples from the past seven years. The lessons?
Stay away from Tech Pubs manager roles that don’t involve any writing.
If you’ve been in the same company doing the same thing for many years, without keeping your skill set current, it can be very difficult to claw your way back if you get laid off.
Make sure you know the tools and technical areas that are in demand. Learn Flare, oXygen, markdown, and some of the more open-source authoring and publishing tools. Tom Johnson’s blog, “I’d Rather be Writing,” is a good resource for keeping current with the latest trends in the field.

About the Speaker

Andrew Davis has been a Technical Communications recruiter in the Bay Area for more than 20 years. As a former professional technical writer and Technical Publications manager, he knows the value that tech writers can add and and the skills that employers are are looking for. For more information and resources, see Andrew’s website: http://www.synergistech.com.

About the Author

Doug Bothwell has been a technical writer since 1999. He has documented a wide range of topics such as optical network planning, TCP analysis and troubleshooting, WAN optimization, web transaction analysis, and application performance monitoring. He is currently a Senior Technical Writer at AppDynamics.

Looking for an Intern?

Over the years, we’ve developed a partnership with the Technical & Professional Writing program at San Francisco State University.

Students from the TPW program are looking for internship opportunities. If your company (or even a nonprofit you’re working with) is looking for an intern, please reach out to info@stc-sf.org so we can connect you with the program director.

The Most Important Election is Here

Time to vote for the San Francisco Chapter leaders! If you are a member of the San Francisco Chapter, you should be receiving an email from Vertical Response to vote.
Not a member of the San Francisco Chapter? What are you waiting for? Go over to stc.org to add a chapter membership. You choice provides our Chapter with funds to continue providing great meetings for the community.
This year, the following volunteers are running for elected positions:
■ Leah Scampoli for President
■ Marc Smirchich for Treasurer
Thanks for voting!

Price Reduction for Monthly Meeting Tickets

Starting in February, the meeting tickets will be lowered by $5 for each type:
■ $5 for student or “special” tickets (see website for details)
■ $10 for STC members (doesn’t need to be a San Francisco Chapter member)
■ $15 for non STC members
We’ve been very lucky to hold our meetings at the Salesforce office for no rental fee and we wanted to pass along the savings to our members.
Don’t worry, the half sandwiches and occasional cookies will still be at the meeting.

TC Camp 2016 is less than 2 short weeks away!

If you haven’t been to an unconference, you should know these aren’t like regular conferences. There are no juried presentations. No powerpoint. No waiting through the next session so you can attend the one you’re really interested in.

You know how it is at a regular conference, the best conversations happen in the hallways. Well, TC Camp is all hallway.

Session topics are chosen by you! They’re chosen by the attendees on the day of the event. Attendees vote on the session topics. Topics with enough votes get scheduled into the agenda. Because you vote on the session topics, you’re guaranteed to find sessions you’re interested in! This is one conference where everything is relevant to Y-O-U. And at the end of the day, in the summary session you can hear about what everyone else learned in all the other sessions.

Want to talk about Documenting APIs? Nominate this topic for a session! Want to talk about wrangling difficult SMEs? Nominate it! (Both of these were topics at previous TC Camps.)

Get all the information on the TC Camp Meetup site.

Smoothing the Transition to DITA (Expert Partners Can Ease the Pain)

Review by Prescott Williams and Nicki Davis

Successful vendor relationships can make or break large, complex projects, but a vendor who’s proficient and successful in one phase of the project might not be the best choice for another part of the job. These are some key lessons shared by Nicki Davis at the August 19, 2015 San Francisco Chapter meeting.

Nicki recounted the process of a large-scale conversion to the Darwin Information Typing Architecture (DITA), breaking the project down into distinct tasks and phases. For each phase, she rated the vendor/partner who helped. Her company management began to rethink their documentation strategy as the product line grew. Not only did they need to produce more content, they had to support that content on multiple devices. In addition, the typical “content silo” effect resulted in duplication of effort and a lack of standard, consistent, user assistance. Perhaps most painful, the company’s content management system (CMS) was not up to the task of supporting the 10,000 — 40,000 pages required to fully support the growing product line. After evaluation of alternatives, it became apparent that:

1. a DITA-based management system provided the best platform, and

2. they needed help.

The project team broke the task into eight sequential steps for which they needed partners:

  • Analyze content
  • Train writers in DITA
  • Train writers in XML and CMS tools
  • Assist with information model (pilot)
  • Assist implementation of CMS (pilot)
  • Create publication scripts
  • Create conversion scripts
  • Clean up migrated content

Partner Tasks

They further determined that four different vendors could best provide assistance, with the tasks grouped as follows:

  • Partner 1: Analyze content
  • Partner 2: Train writers in DITA; Assist with information model (pilot); Create publication scripts; Create conversion scripts
  • Partner 3: Train writers in XML and CMS tools; Assist with implementation of CMS (pilot)
  • Partner 4: Clean up migrated content

The work of Partners 1, 3, and 4 was consistently excellent, rating A across the board.

Content Analysis

Content analysis by Partner 1 isolated specific problems with existing documentation and developed a set of design goals to address them all. Among other objectives, the project would deliver documentation in one place that supported:

  • Navigation
  • Search
  • Versioning
  • Governance (clear ownership)
  • Review and comment
  • Analytics

Training and Pilot Projects

Training programs for the writers, from two separate vendors (Partners 2 and 3), were effective as well. DITA training was a separate curriculum, done by Partner 2. As might be expected, the same vendor (Partner 3) provided CMS training and assisted with the six-month CMS pilot project that immediately followed to reinforce the training. Writers devoted 20% of their time to the new system during the pilot.

Partner 2, in addition to providing DITA training, assisted with the information model and effectively met all requirements. But in the development of publication and conversion scripts, they were less successful.

Markup and Scripts

Preparation of the existing content for export from the original CMS required close examination and analysis. The team marked all topics with the relevant DITA information type (task, concept, or reference) and prepared detailed inventories of shared topics, shared graphics, and “conrefs” in the original material. Conrefs would enable content from one topic to be pulled into another topic in the assembly of user documentation.

Then, Partner 2 was charged with writing scripts to convert the XML from the old CMS to DITA, and in turn publish the desired output from the new CMS. It did not go well.

Script-writing turned out to be much more difficult than anyone – Partner 2 or Nicki and her colleagues – expected. Writing scripts for publishing from DITA, which they expected to be a routine task, turned out to be anything but. The published output had no consistency, with additional line breaks inserted apparently at random. The problem was solved eventually, but not without a great deal of angst. As for the conversion scripts, the team was prepared for a certain amount of manual cleanup because of the need to properly characterize every chunk of information. Nicki referred to this requirement as the need for “intelligent content.” Intelligent content requires semantic markup, and semantic markup requires tagging each chunk as to its purpose.

For example, two steps in a set of instructions may each be followed by a one-sentence paragraph. But one paragraph may give the results of the instruction (“The X dialog box appears.”) while the other gives a screen location (“The ‘Enable’ check box is at the bottom of the dialog box.”) Unless the paragraphs have been marked up properly as “<stepresult>” and “<info>” they will not be converted properly. The team did not expect the conversion script to apply the correct semantic tags to such paragraphs, but did expect the script to mark paragraphs within steps with a single default semantic tag (for example, “<info>”). Paragraphs that were marked with inappropriate semantic tags would need to be identified by writers and re-tagged manually.

Surprisingly, the team was unable to create a script that could recognize the difference between numbered paragraphs and indented non-numbered paragraphs within steps. The script converted every paragraph in the procedure to a numbered step. For example, a procedure with two numbered steps and two non-numbered indented paragraphs would be converted to four numbered steps. In addition to that, text within paragraphs would be duplicated and merged into the preceding paragraph. Needless to say, cleaning up this content required much more work than simple re-tagging. Partner 2 rated A in training and information modeling, but lacked experience with conversion and publishing. Their deliverables, rated D and F, required two additional writer-years of manual cleanup to complete the project.

Lessons Learned

The writers on the project were challenged by the move from unintelligent to intelligent content, but it gave them a new understanding of their own material. Management learned that vendor expertise in one area doesn’t ensure expertise in another. At the same time, overall the company concluded that even with the difficulties, the efficiencies of outside training and help with content analysis and modeling showed the value of finding partners to assist with large-scale DITA conversions.

About the authors

Nicki Davis, PhD, is a Senior Technical Writer at Complete Genomics, Inc.

Prescott Williams, currently Treasurer of the Sacramento Metro Chapter, wants to grow up to be a “DITA stringer.”

Haven’t Renewed for the STC? Get a Free Chapter Membership!

Members who join or renew before June 1, 2015, will receive a free 2015 membership in the referring Chapter or SIG.

Important: Don’t sign up or pay for the Chapter or SIG; instead, include the San Francisco Chapter as a referral on the online application. The referral fields can be found under the Membership tab of the online application. STC will be responsible for signing the member up for that particular Chapter or SIG free of charge. The San Francisco Chapter must be listed online to receive credit.

Free Webinar on February 25: Joe Welinske on Techniques for Mobile User Assistance

The STC San Francisco Chapter is hosting a free, live webinar featuring Joe Welinske on Techniques for Mobile User Assistance on Wednesday, February 25, 2015, at 7:00 PM PT.

Email info@stc-sf.org by Monday, February 23 to save your spot!

About the Presentation

Smartphones have sparked a huge, new software segment – the mobile app. This creates an important pair of questions for user assistance professionals: What is our role going forward in mobile and how can we prepare to take that on? User Assistance does have a role in supporting mobile apps. As the mobile app market continues to soar, this is becoming the next frontier for user assistance professionals. This session provides an overview of current issues regarding design, writing, tools, and planning of your mobile UA.

You Will Learn

  • About contemporary design for user assistance in mobile apps.
  • Why traditional desktop UA translates poorly to the small screen.
  • What techniques are particularly useful to employ.

About the Presenter

Joe Welinske specializes in helping your software development effort through crafted communication. The best user experience features quality words and images in the user interface. The UX of a robust product is also enhanced through comprehensive user assistance. This includes Help, wizards, FAQs, videos and much more. For over twenty-five years, Joe has been providing training, contracting, and consulting services for the software industry. recently published the book, Developing User Assistance for Mobile Apps. He also teaches courses for Bellevue College, the University of California, and the University of Washington. Check out the Events page for upcoming classes and industry presentations.

About User Assistance Boot Camp, Seattle – April 15-17

We’re going to hit an aggressive agenda at WritersUA West with two separate sequences of UA-specific learning – for newbies and pros. “UA Boot Camp” features certificates in Basic Training and Grad School. Over thirty sessions covering all aspects of software user assistance. Registration is just $695. Read the conference details.

Important Webinar Information

  • Space is limited to 25 people
  • Please register by Monday, February 25
  • Email your name and email to info@stc-sf.org to register. The presenter will send you an email with the connection information.
  • The webinar will be presented using GoToMeeting
  • The webinar will be streamed live and will not be recorded
  • The presentation is scheduled for 45 minutes and there will be time for questions at the end

January 24, 2015: TC Camp

TC Camp is an Unconference focused on Technical Communications issues, skills, challenges, and the various applications used by technical communicators.

The purpose of TC Camp is to provide a local conference for technical communicators that is driven by the members of that community–writers, editors, designers, and the people who support them.

Visit the TC Camp website for full details on the location, agenda, ticket price, and attendees.

Date: Saturday, 24 January 2015
Time: 8:30 am to 6:00 pm
Venue: Hospitality Management building, Mission College, Santa Clara, CA.
WiFi will be available, you can twitter, live blog!
Register on TicketLeap: choose a workshop or just attend the afternoon unconference

  • Workshop + Unconference + Lunch — $39
  • Workshop + Unconference — $35
  • Unconference + Lunch — $4
  • Unconference Only — Free