Meet the New Generation of Technical Writers at San Francisco State

At the July, 2016 meeting, Neil Lindeman, Ph.D., Associate Professor at San Francisco State, talked about the Technical Writing Program at SFSU as well as their Internship Program. This meeting was summarized by Floyd Smith.

STC-SF Meeting: Wednesday, July 20th, 2016

Leah opened with announcements.

Neil Lindeman, SF State

Director of Technical Writing Program

Ex-editor at Conservation International

Meet the New Generation of Technical Writers at SF State

Technical and Professional Writing – Only major program in California!

  • Program dates back to early 1990s.
  • Golden age through dot-com boom and even to ’08 financial crisis. They’re rebuilding now from some lower enrollments and funding challenges. DITA and online help courses have gone missing, with 20-student minimums. They are now more online-oriented.
  • Administratively, they’re becoming a concentration in the English major. 30-40 active major students and 20-30 minors (24 units = 8 classes), plus certificate program w/5-10 people (same requirements as minor).
  • Focus can be technical writing or development work etc., which is professional writing. 30% go to tech writing, rest want to be less technical.
  • Required: Fundamentals class, “technical promotional writing”, document design. Minor of some kind; can be information systems, instructional technology, computer science. For professional writing, can be marketing, non-profit communications, graphic design.

Internship Program

  • Students who are near graduation.
  • Develop job application materials, including coursework.
  • Length is 120 hours of program-related work, ideal for it to all happen in one semester (16 weeks).
  • Students need to be pro-active about finding internships. About one-fourth of internships are paid (perhaps $20/hr) and three-fourths unpaid.
  • Internship sponsor evaluates the student and recommends their grade!
  • No one ever takes it for more than one semester, it would cost them tuition, but the internships – usually paid ones – go on.
  • Do businesses that hire get to see the reflective report at the end? Not usually.

Example: Parrot, Amanda’s Internship

  • Researched documentation needs of the customer support team
  • Presented on 10 potential projects
  • She did first project from her list, wiki based on Confluence, including development and training
  • They hired her for a 6-month contract to finish and train their staff.

Final notes

  • Try for structured and well-defined internship projects
  • Tech Writing focus usually works well, it can be harder to find structure on the Professional Writing side

Q & A

  • Are most students as strong as Amanda? No, they try to fit the internship to the student, and Amanda was a star.
  • How do they get tech experience? Some have a technical background and then come to the program. Others come from English major background and try to fit into technical side. You can do independent projects and submit them. Or join open-source projects! Can include term papers. IBM has a co-op program.
  • Certificates: Costs about $10K, but they also have Open University access for empty seats, with their own free structure; there are often seats.
  • Terms: There are sponsoring programs and supervisors.
  • Ideal: Paid programs with established offices in SF and some remote work allowed.
  • Difficulty? Students have trouble finding paid internships. Only 7-8 students are looking for an internship each semester, only 2-3 of them have a tech focus. Could tie into a CS internship program.
  • There are still opportunities for the fall.
  • Others: Berkeley has an extension program; Carnegie-Mellon has a campus in Mountain View. UC Santa Cruz has an extension in Santa Clara.

Contact information

Neil Lindeman, Ph.D., Associate Professor at San Francisco State.

1600 Holloway Avenue, HUM 423

San Francisco, CA 94132

Phone: 415-405-0493

Also: Cal Berkeley will have a job fair in the fall.

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,, 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:

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.

Git Demystified for Non-programmers

At the March 2016 meeting, our presenter Jimmy Cuadra gave an introduction to the version control system Git. He described the key concepts behind Git and cleared up common misconceptions. This meeting was summarized by Juan Lara.

What is Git? Git is a distributed version control system that saves the state of files. It’s the version control system most frequently encountered in new projects. Projects do not always use the “distributed” functionality of Git.
Why should writers care about Git? Git is the lingua franca of many developers. Also, Git is increasingly being used outside of software development. For example, you can use Git Hub Pages to run a blog.
What is a Git Blob? Git tracks the contents of a file and not the file itself. All content is stored in a Blob object.
What is a Git Tree? A git tree keeps track of the hierarchy of a repository. It can contain Git blobs or other git trees.
What is the Commit command? The Commit command creates a Git Commit which is a snapshot of files frozen in time. The command creates a tree of blobs using an ID and meta-data. The ID maps to the content in the blobs. One important concept to understand is that the ID directly maps to the contents of a file. Meta-data includes time, person creating the commit, and a commit message.
What is a Git Repository? A Git repository is a database of Git objects including a history of every commit.
What is a Git Branch? A branch is a named Commit. It’s the flagship feature of Git and developers love to branch all over the place. Branches allow you to work on a crazy idea without breaking the main project branch.

Networking for Introverts

The San Francisco chapter’s April 2015 meeting featured Rebecca Firestone, an award-winning technical writer, content developer, and trainer with 20 years of experience in startup and corporate environments. This meeting was summarized by Laurie Bouck.


Most technical writers are introverts, yet the job search process, with its emphasis on networking, seems to reward extroverts. How can those of us at the quieter end of the personality spectrum be effective at networking, a key career-building skill? At the April STC meeting, senior technical writer Rebecca Firestone explained how introverts can network in ways that work for them.

Introverts recharge through solitude; seek peace, sanctuary, and beauty; and have an active inner life. They also can be successful leaders; famous introverts include Abraham Lincoln, Bill Gates, and Barack Obama. Extroverts, on the other hand, thrive around other people and prefer to work in groups, which Firestone pointed out sounds like a contemporary job description.

Networking to Fit Your Personality

For introverts, Firestone said, networking can feel phony, especially when we’re told that networking is easy and we just need to “lean in.” Networking does not involve asking strangers for a job or following any networking book too literally. Instead, we need to recognize that networking takes time, like cultivating a garden. When approached this way, Firestone said, networking is intrinsically rewarding.

To network successfully as an introvert, Firestone recommends the following:

  • Interact with each person you meet as if that person might be important to your success—like a little sprout in the garden that might thrive.
  • Look for opportunities to talk and network with people you already know, such as friends and colleagues at meetings of professional organizations.
  • Think about one to three topics or activities that interest you this week, and use these ideas to start conversations with others at events.
  • Ask your colleagues what was your “secret sauce” that helped you shine in your work. Use these stories to tell others about yourself in a natural way.
  • Use a little social lubricant, such as a glass of wine, if it helps you relax at events (just don’t overdo it!).
  • Avoid being calculating, too self-promoting, or badgering people when networking (think of how off-putting these behaviors are in a singles bar!).

Networking is a lot like fishing, said Firestone. It takes patience. You must set multiple lines to catch something. When the line wiggles, respond immediately, but keep your cool and don’t overwhelm people—stay calm. Let the person come to you.

Make networking a regular practice. Like dating or house-hunting, Firestone explained, as you network you will realize that there is an abundance of opportunity. Good networking resources include professional associations, alumni associations, and previous employers and colleagues. You can also connect with others by sending holiday and birthday greetings to catch up with people, and writing high quality blog posts to showcase yourself and your skills.

Managing Obstacles to Networking

Firestone said that it’s important to recognize common obstacles to successful networking and develop ways to overcome them. These obstacles, and their work-arounds, include:

  • Desperation: To avoid reaching this point, plan ahead and don’t wait until your hour of need to start networking.
  • Anxiety: To manage anxiety, prepare for networking opportunities, such as bringing index cards with icebreaker topics written on them to review before you go to an event. In general, try to avoid feeling anxious about the job search, so that (for example) you don’t feel crushed if you don’t get the first job you interview for.
  • Fear of looking foolish: To manage fear, remind yourself that everyone else is worried about how they are perceived, too. They don’t notice your fear as much as you think.
  • Inertia: To overcome inertia, start small, with a low-stress person or event.
  • Despair that you’ll always be bad at networking: To counteract despair, rejoice in small networking successes.

Making Networking Fun and Meaningful

The job hunt is easier if you have fun doing it, Firestone said. For example, use a software tool to create a silly or fun project. You can use the project as a writing sample, and it also showcases your personality.

Take the time to learn about something you’re curious about that has some connection to your work. Your interests can help you connect with others in a meaningful way and can expand your career opportunities. Be open to the fact that one thing can lead to another.

Look for people who are applying the topics you are learning about (not experts who are promoting themselves), and ask them about their work. Most of them will be happy that you are interested in their area of expertise.

Try to give rather than take in order to optimize networking, Firestone said. Volunteer for STC, or mentor others, and be generous with your time. Respond quickly and courteously when you are asked to do something. Do meaningful favors for people and provide relevant referrals. The success of others is your success too, and it will build your confidence.

Remember that life paths do not always go in a straight line, Firestone said. Even successful people make big mistakes but still succeed, so be kind to yourself.


About the Speaker

Rebecca Firestone started as a technical writer in 1988. Since then, she’s worked in telecom, customer relationship management, architecture, clean energy, and software training. In her most recent role, Rebecca expanded her scope from pure writing to include strategic planning and workload scheduling, learning on the job by trial and error. Most recently, she just completed a stint as a Senior Technical Writer at SolarCity Corporation’s product development office in San Rafael, CA.


About this Review’s Author

Laurie Bouck has worked as a writer and editor for over 20 years, covering health topics and consumer technology for clients such as Blue Cross/Blue Shield, McGraw-Hill Online, Alpha Books/Penguin, and CNET. She moved over to technical writing and project management in 2012, and worked most recently at Pacific Gas & Electric Company, revising maintenance and repair documents used in the field.

How to Make Version Control System a Technical Writer’s Best Friend

The February 2016 meeting featured Richard Mateosian, who discussed version control systems. This meeting summary was written by Calvin Yee.

As technical writers, you will encounter version control systems (VCS). If you’re anything like me, a VCS can be confusing and challenging to use. At the February 2016 STC-SF chapter meeting, our speaker, Richard Mateosian, demystified how a VCS works and how using it well help you be a better member of a software development team.

Mr. Mateosian said that there are parallels between what technical writers and developers do when creating a software product. For example:

  • Developers build software components and writers create topics.
  • Developers build the software so it can be tested and writers build documents so they can be reviewed.

Because the processes are similar, any tools that developers and writers can share for creating the product is a good thing.

One of these tools that’s shared is a VCS repository (“repo”). A repo mainly handles text files. Developers handle files that contain code while writers handle files that contain topics or mapping information.

How a Repo Works

A repo provides the following features that are crucial to developing complex software:

  • Keeps track of current and older versions of your files.
  • Keeps track of related files for a project. This is generally the source files for building software packages or documents.
  • Allows for the creation of a Master repo and branches within a repo to manage the complexity of a development project.
  • Includes tools for manipulating files such as checking files in and out, merging files, comparing file versions and keeping a log of changes.
  • Integrates with other tools.
    NOTE: Repos handle text files the best (for diffs and merges), but they don’t handle non-text files as well (such as binary objects, or proprietary files like FrameMaker) nor do they understand the contents of a file nor do they perform component content management (CCM).

Using a Repo

The basic workflow steps for using a repo are:

  1. Maintain a local copy of the repo on your machine.
  2. Keep the local copy in sync with the master repo.
  3. Make your changes and test them locally.
  4. Commit the changes from the local copy of the repo to the master repo.
    NOTE: Committing a file to a repo is a formal way to get the files into the build system to create the software product.

Types of Repos

A VCS repo is either centralized or distributed. The differences are:

  • To use a centralized VCS, you must be connected to the central server to be able to do anything with a file. (Perforce is an example of a centralized VCS.)
  • To use a distributed VCS, you do not need to be connected to the central server (or “master repository”) to make changes to a file. The reason is for a distributed VCS, you are working on a complete copy of the master repository that you downloaded on your local machine. Thus, you can make all the changes you want to a file, create a branch, and so forth without having to be connected to a centralized server. (Git is an example of a distributed VCS. In Git, making a complete copy of a master repo is called “cloning the repo”.)

Features of a Repo

There are three main features that a repo provides:

1. Locking Files

Repos have a locking mechanism to restrict access to a file while it is worked on. The locking mechanism prevents someone else from overwriting your changes or yourself overwriting someone else’s changes in the same file. Repos offer two types of locking mechanisms:

  • Pessimistic locking – You check out a file, which then locks out all other users from editing it. Once you’ve made your changes and check the file back in, then another person can check it out. The assumption is “nothing good will happen if more than one person works on a file at a time”. Subversion and Perforce use this type of locking.
  • Optimistic locking – You check out a file and tells others that you’re working on it without locking it. The assumption is that most changes don’t interfere with each other. Git uses this type of locking.

2. Creating a Branch

To allow for different parts of the software to be developed in parallel, a repo allows you to create branches. This allows different users to work on their part without stepping on other’s work.

This is the workflow for creating a branch in Git:

  1. Create a branch & track it on the “origin” repo.
    NOTE: The term “origin” refers to the location where you made a copy of the source repository.
  2. Make and test changes locally.
  3. Sync the local repo with the origin repo and issue a pull request.
  4. Submitter and reviewers discuss the changes until everyone says LGTM (“looks good to me”).
  5. An authorized user (could be you) merges your branch into the master (the origin repository).
  6. You delete your branch.

Users like Git because it’s easy to create a branch with relatively low overhead (compared to a system like Perforce). In Git, you can think of a branch as a list of pointers. Because you are working with a local copy of a repository, you can do endless pulls from the master repo. This makes it easier to merge the changes back into the master repo.

The main difference between Git and GitHub is that Git is strictly a VCS and GitHub is a website that houses multitudes of projects.

NOTE: A “pull request” is a GitHub-specific review mechanism. It is a way to get reviewers to look at the code or file before it is merged into the master repo. (Reviewers typically receive an email notification of the pull request.)

TIP: To view all the branches for a Git repo, use “git branch”.

3. Performing Merges

When you want to bring the different branches together, you perform a merge. Merging is about putting changes from a branch back into a master copy. The workflow for merging is:

  1. Check out the file.
  2. Make changes.
  3. Check it in.
  4. If the VCS sees a conflict, use its tools to resolve it. The tools let you see both persons’ changes.

Some participants offered their observations about handling merge conflicts:

  • Ask other users roll back their changes so that only the correct changes go through.
  • Ask another human to review a merge conflict. The VCS may not always be correct when it generates a merge conflict. For example, if a user checked out a file but never checked it back in, this can generate a merge conflict.
  • Communicate with your co-workers to coordinate the changes made in a file to minimize merge conflicts.

Other Helpful Tools for the Developer Environment


If your company wants to implement a DITA system but does not have the budget to implement it, there are options to implement a smaller DITA-compliant system. The “bare bones” for this system are:

  • oXygenXML for editing and publishing (this is a “paid” tool that is DITA-aware). This tool keeps track of the DITA maps.
  • Jenkins (formerly called “Hudson” because Oracle trademarked this name) for automating the build process. Jenkins is a Java-based tool.
  • Git for managing content and version control.
  • DITA Open Toolkit for generating the documentation output.

Source: Eliot Kimber, DITA for Practitioners

Issue Trackers

Because creating software is a complex endeavor, you need to track issues to keep the product development on schedule. Issue trackers can be specialized such as ZenDesk for support tracking. JIRA or Bugzilla for developer-issue tracking. However, all these tools share the same capabilities, which is the ability to track tasks, defects and comments about them.

This is the issue tracking workflow:

  • Someone reports an issue.
  • People Comment.
  • Assign issue to someone.
  • Make changes and others review and comment.
  • Designated reviewer closes the issue.


Mr. Mateosian emphasized that using the software development tools is not enough by itself. To become a more effective member of the development team, he offered the following tips:

  • Be an active part of the team!
  • Understand the process you’re a part of (you must make yourself a part of it—even if you don’t feel like it!)
  • Be an active participant in all the communication spaces (chat, email, Slack—which is another chat mechanism where you set up a group so everyone can communicate in one place).
  • Take charge of documentation review—make it efficient. The bottom line is don’t waste the developer’s time.

About the Speaker

Richard Mateosian is a fellow of STC and has extensive experience as programmer. His road to becoming an API technical writer was a very winding road. He began as a mathematician, then became a developer, followed by a technical marketer, before becoming an API technical writer. If you have further questions or comments for Richard, you can reach him at

Link to the slides from Richard’s presentation.

Salesforce Trailhead: How two teams converged to blaze a new trail

The San Francisco chapter’s January 2016 meeting featured Lauren Grau and Kim Shain, both from Salesforce, Inc., presenting Salesforce Trailhead: How two teams converged to blaze a new trail.

Something New Under the Sun

Most technical communicators would agree that when it comes to information products, Ecclesiastes 1:9 has it right: What has been will be again, what has been done will be done again; there is nothing new under the sun.

On the other hand (and with apologies to George and Ira Gershwin), there’s Gershwin’s theorem: It ain’t necessarily so. Salesforce Trailhead reinvents the way new Salesforce developers, administrators, and users learn Salesforce. Rather than an online help system or traditionally structured tutorial, Salesforce Trailhead uses gamification to lead learners along a series of virtual hiking trails. Each trail in turn comprises a set of targeted learning challenges.

Underlying Trailhead’s innovative approach is the integration of marketing automation and social media into Trailhead’s game-oriented learning cycle. To both encourage learners to begin and then keep going, and to provide learners with a visible measure of their progress, Trailhead:

  • Awards publicly displayable points and badges when learning challenges have been completed
  • Highlights learners’ successes on community profiles
  • Celebrates the completion of learning challenges on social networks

Providing clear feedback to individual learners in the form of points and badges, while at the same time enabling one to measure one’s progress against other learners, has made Trailhead unimaginably popular with its large and growing community of enthusiastic Salesforce developers, administrators, and users.

Salesforce Trailhead truly is something new under the sun.

Two Teams, Many Contributors, One Goal

The subtitle of Lauren and Kim’s presentation — How two teams converged to blaze a new trail — merely hints at the complex set of collaborative interactions required to design and deliver Salesforce Trailhead.

In many companies, tech pubs, marketing, and product development refer to each other as “those guys”. Or worse. But when it came to Trailhead, Kim and Lauren needed to make collaboration between the documentation, marketing, and Trailhead product development teams more than a management buzzword.

And they needed to do it quickly: To enable Trailhead to be soft-launched at Dreamforce 2014, the project team needed to deliver an initial version of Trailhead, including an initial set of learning challenges, in only ten-weeks.

The combined team first needed to understand each other’s different working styles and technical vocabularies. Shared values and mutual trust enabled the unified project team to create Trailhead learning challenges at the same time that the product was being developed.

At the time that Kim and Lauren delivered their presentation to the chapter, they were able to provide the following concise retrospective on their teams’ successful collaboration:

  • Focus on shared goals and principles: Use shared values to make decisions and resolve differences of opinion, be sure your assumptions about terminology, et cetera, are valid.
  • Commit to a deadline: A tight delivery date can be made to work to your advantage, focus on delivering a minimum viable product.
  • Assemble a critical mass of supportive stakeholders: Start with a proof of concept (or two), be sure to market the project internally.
  • Put customer needs first: Love your community, don’t be afraid to try something new.

But Does It Work?

Trailhead was an immediate success. Two weeks after going live in October 2014, Trailhead generated more than 1,500 social media postings and more than 20 community-authored posts. By the time Kim and Lauren delivered their presentation to the S.F. chapter on 20 January, 2016, Trailhead’s adoption rate comprised:

  • Month-over-month growth in active users of 40-percent
  • Month-over-month growth in badges earned of 50-percent (more than 250,000 challenge-completion badges so far)
  • More than 175 user-authored blog posts praising Trailhead
  • More than 71 modules and projects

Obviously, then, Trailhead is working. So well, in fact, that one year after its soft-launch, Trailhead was a featured presentation at Dreamforce 2015.

Maintaining User Momentum

Behind Trailhead’s impressive-user-acceptance numbers was another key contributor to Trailhead’s success: sophisticated data collection and analysis.

Trailhead’s criteria for success was defined as the:

  • Number of learning path page views
  • Number of Trailhead learners who completed at least one challenge
  • Number of learning challenges completed across the entire Trailhead users community
  • Percentage of new Salesforce developers who became active

To achieve those goals and keep Trailhead learners on the figurative trail, Lauren’s Trailhead Marketing group constructed an action-based, personalized marketing campaign that, among other things:

  • Tracks and incentivizes learner activity, not just page views
  • Guides different categories of Trailhead learners to the appropriate trails and challenges
  • Uses targeted email to encourage learners to remain active
  • Announces new content to Trailhead users
  • Conducts Trailhead Live global meet-ups, webinars, and workshops

The key point is that another of Trailhead’s important innovations is the recognition that it’s not numbers alone that matter, but rather how those numbers can be used to measure, and if necessary improve upon, Trailhead’s ability to transform new Salesforce developers, administrators, and users into committed Salesforce customers.

References And Links

When discussing the many challenges required to build Trailhead’s collaborative Developer Marketing + Doc & User Assistance team, the presentation cited the following two books:

  • The Collaboration Imperative by Ron Ricci and Carl Wiese
  • Behind the Cloud by Marc Benioff

You can also experience Salesforce Trailhead for yourself at

About This Review’s Author

Riley VanDyke has been a contract and consulting technical writer since 1998 and is an STC-SF chapter volunteer.

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.”

Case Study — Information Design: A Process for Web Architectural Success

Review By Riley VanDyke

The chapter’s Wednesday 20 May, 2015 meeting featured Eric Hughes’ presentation, Information Design: A Process for Web Architectural Success.

Eric described how he and his colleague Don Donoughe guided the University of Arkansas (UofA) through a re-implementation of the university system’s online Cooperative Extension Service.

The Backstory

At the time that Eric became involved with the project, the University of Arkansas’s Cooperative Extension Service website:

  • Struggled to serve a large and growing body of disparate target audiences who resided in all of the state’s 75 counties
  • Comprised an estimated 10,000 documents, the great majority of them stored as PDFs
  • Frustrated new visitors who were unable to use the site’s labyrinthine lists-of-lists navigational structure to find useful information
  • Forced existing users to create collections of bookmarks that enabled them to return to useful information they had somehow managed to find on a previous visit
  • Had as an internal team failed over a couple of years to redesign the site

The Organizational Challenge

It would have been difficult enough to solve the site’s manifold information architecture problems. Before those problems could be approached, it was first necessary to overcome predictable and unpredictable organizational obstacles.

The Cooperative Extension Service site was and is developed and managed by the UofA. This put the site in the hands of academically oriented contributors who buried the project team beneath a landslide of committees, processes, flowcharts, data, and alternative design proposals.

How Can We Help?

The UofA realized it needed help. So it invited Matriculus and design partner Donoughe Design to present a new way forward.

At the core of the presentation Eric delivered in response to that invitation were the following answers to the rhetorical question, Why Hire Us?

  • We’ll teach you to manage the site as a product.
  • We’ll tell you how we’ll know when we’re done (Or the reason you do process is to define an end point).

Observe that neither of these answers mention technologies, tools, or information architecture. Instead, those are criteria defined the project’s goals in terms of quantifying effective process and quantifying a successful result.

To the Rescue!

In response to Eric’s presentation, the University of Arkansas awarded Eric and Don the contract.

One of the first steps was to find someone on the project team who had the organizational authority the team would need to break process logjams, acquire necessary resources, and enforce order.

Having had the good fortune of a strong central contact within the UofA project team, Eric could begin focusing and distilling the previous team’s overabundant contributors and analysis data.

Whittling Down the Contributors

The re-architecting of the Cooperative Extension Service’s  website was a highly visible project and many people wanted to be seen as contributors.

Fortunately, Eric’s UofA contact had the authority to break process logjams and acquire the resources required to get things done. This individual’s authority enabled her to pare down the size of the project team to a manageable number of results-oriented contributors.

Whittling Down the Analysis Data

The preceding project team had created an overabundance of focus-group data, online surveys, log reports, executive team surveys, process diagrams, flowcharts, and more. Eric and the now-downsized project team next distilled the existing into a small subset of information, conclusions, and assumptions.

One example illustrates the scale of the problem and the steps necessary to distill the volume of data into a more useful form:

  • Before Eric became involved, the UofA project team had defined 30 target audiences for the site
  • Eric and the new UofA team distilled that list into a subset of target audiences that served as proxies for the larger, less focused set of audiences

Let the Information Architecting Begin!

Only after assembling a smaller, focused team and extracting the useful portions of the previous team’s research data did Eric feel ready to develop the site’s new information architecture.

The team used data acquired from user interviews, usability testing of design mockups, and card sorting sessions to develop a 10-page “key problems & issues document”. The key document provided a single and concise declaration of the project’s scope, objectives, and criteria for successful completion, and summarized all the previous information and analysis that had been done.

The Happy Ending

The size and complexity of the project to redesign UofA system’s Cooperative Extension Service website is impossible to convey in this brief recap of Eric’s presentation to the STC-SF chapter meeting.

What is summarized in the following paragraphs is the project team’s fundamental strategy, and the essential steps the team took to fulfill their strategic goals.

Discover and build on what has already been done: Identify the useful parts of earlier work, but don’t let the project become a prisoner of data that doesn’t help realize the project’s current goals.

Document the design and project process: The objective is not to communicate what needs to be done, it is instead to clarify what the team will need to do. Having documented the process, be ready to modify the process as required to achieve evolving needs.

Discover and address the real problems: Don’t let peripheral issues, constraints, and political quandaries diffuse the team’s efforts.

About This Review’s Author

Riley VanDyke has been a contract and consulting technical writer since 1998 and is an STC-SF chapter volunteer.

Streamlining Graphics Production in a Hardware Industry

Presented by Bonnie Kim

Visual Aids by Rebecca Firestone

Review by Mysti Berry

Technial writer Bonnie Kim shared with us the story of how ZepSolar adjusted  processes and tools to create graphics-dependent documentation in print and video more quickly.

The process originally involved creating graphics from scratch whenever any changes occurred, because the graphics had to move across a complex tool chain: from a library of specifications to SolidWorks, Adobe Acrobat, Jing, Photoshop/Illustrator, and InDesign/FrameMaker. Changes due to inconsistent visuals, product design changes, or content errors meant starting over.

Bonnie’s team stopped editing files in PDF and Jing, and started doing all editing of files in SolidWorks Composer, reducing many of the round-trips required when changes occurred. The team used more sophisticated SolidWorks tools, like transforms and annotations (labels, arrows, and “diggers”), to make production of the graphics faster.

Animation for video is also easier to create because SolidWorks has sophisticated tools that make many things easier, like specifying camera view (also available for print graphics), or intelligent views that save the placement and orientation of components or sets of components. They can apply the same transformation across many static views, and save the transformation for later use.

With the tools adjustment, the workflow is a simpler process, from pulling specifications from a library through SolidWorks assembly, composition, layout, and edits. Of course, every tool has its strengths and weaknesses. Bonnie shared with us that imports can be tricky in SolidWorks; it has a high price tag, and there are a few bugs in the program. Nonetheless, the professional look and feel, new vector-graphic capabilities, and small, efficient files all make SolidWorks the right solution for her team.

Bonnie’s changes can be applied to software documentation production as well. Simplifying your tool chain and reducing the number of repeat round trips required for any task applies to software documentation as easily as hardware.

Bonnie recommends that every team learn the product they are documenting as thoroughly as possible, and then get training for your tool as it likely can do more than you realize, and then, let members of your team specialize. Of course, everyone should have a certain level of versatility, but when deadlines loom, specializing in certain skills can speed up production.

You can find out more about ZepSolar at, and SolidWorks at

Technical Recruiter Shares Expertise

Review By Doug Bothwell

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 what companies are looking for.

Thanks to Mysti Berry and Salesforce, the San Francisco STC chapter was able to book a large training room to handle the high turnout on February 18. The presentation was split into a prepared talk and a Q-and-A session.

Part 1: Make Yourself Marketable

Highlights from Andrew Davis’ presentation:

  • Mobile, Big Data/Analytics, SaaS/virtualization/cloud, Security, Open Source arenas are hot
  • Open-source companies often sell documentation–that’s how many of them make money
  • Technical Knowledge–Train yourself and become marketable. Some helpful resources include:
      • MOOCs (massively open online courses) are the answer to your prayers, and ignoring them is self-sabotage. Explore one or more of the following—register, learn, and write something using your new knowledge:
      • Trialware is the other answer to your prayers
      • Online resources for would-be API writers:
      • Write The Docs meetups in SF (or, better yet, the Portland, OR conference in the spring)
  • Opportunities and Leads:
      • Networking (still the best)
      • Recruiters
      • Job boards—Beyond the obvious choices, here are good ones:
        • LinkSV for discovering off-the-radar prospects
        • LinkUp for current, under-publicized listings
  • Employers are looking for people with
      • Excellent research, analysis, organization, writing, editing, and production skills
      • Autonomous technical learning and tool/system troubleshooting ability (aka fearlessness)
      • Deep interests in one or more technical sectors and current technical tools/development languages
      • Software experience, ideally involving some code-reading, code-commenting, and even amateur programming

Contact Andrew directly for more from his Help Me Help Your Resume document at his website

 Part 2: Q & A with Andrew Davis

“What are the skills that companies want in writers but have the most difficulty finding?”

Software development skills–folks who can develop in their own environment without any help. Many development teams are looking for someone like them (i.e., fellow developers) who can and want to write, but these candidates are difficult to find. They want people who can write documentation that gets newbie developers up-and-running with key features as quickly as possible (ie, a short TTFHW–“time to first ‘Hello World’).

“What kind of volunteering work looks good on a resume?”

Work for professional organizations related to the Tech Comm field–it shows you believe in your profession. But don’t just limit yourself to STC–there are lots of other organizations out there. For example, Write the Docs has regular meetups that are well-attended by writers in the open-source space. These folks are more focused on deep dives into technology and supplying relevant content to developers; they’re less focused on authoring tools, DITA, and other topics that are primarily of interest to tech writers.

“How do you answer the interview question: ‘Where do you see yourself in 5 years’?”

You should answer this question seriously, even if it might be kind of old-school. It’s best to say something like “I want [more of what I want],” without getting too specific. Consider this an opportunity to tell them something about you that they don’t already know, that’s not on your resume, but emphasize how your goals can benefit theirs.

“Many interviewers don’t like interviewing and are not very good at it. Their questions are often vague and not targeted. How can I help them get the information they need?”

You should be able to say, in three minutes or so: “Here is what I’m guessing you need, here’s how I can meet those needs, and here’s the proof that I’ve done so.” An audience member suggested that you ask: “What are the biggest problems you have regarding documentation?” This offers you a chance to show how you can solve their problems; Andrew agreed, but said you need to be careful not to sound too strident nor too modest. There are times in an interview when the person who talks the least wins.

“How do you handle the issue of no-reference policies that many companies have today?”

One way to handle this is to ask someone for a LinkedIn endorsement that stays unpublished until after the person leaves the company. Also, some people might be willing to provide “off-the-record” endorsements. Note: If you contact someone asking for a reference/endorsement, it’s best to do it via cell and to do it after hours.

Someone pointed out that many companies don’t give out bad references these days for legal/CYA reasons. Andrew said that’s true, but some people still give bad references off the record.

“Are companies still unreceptive to candidates from outside the industry?”

Yes, so highlight experience you have that’s relevant to the position you’re looking for. It shows you’re in touch with their requirements.

“How do you deal with people who have no idea what tech writers do?”

Talk to them in terms of the problems you can solve and the money you can save and/or make them. You need to be able to “show your stuff” and get specific about the ways you can add value. Tech writers can do a lot beyond simple wordsmithing! And everyone cares about looking good on paper.

“Where do you see the field in five years?”

Most API documentation will probably be automated in five years, though tutorials and getting-started documentation probably won’t. UI/UX documentation probably won’t be automated. A very useful skill is being able to assemble teams and get things done…but beware Tech Pubs Manager or Doc Manager roles if they don’t involve creating product-related content.

Check out Andrew Davis’ website,—it’s a huge treasure trove of valuable information for folks looking for work, and those looking for workers.

Doug Bothwell has been a technical writer since 1999 and is currently a Lead Technical Writer with Riverbed Technology in San Francisco.