Meeting Notes from September 2018: Hiring Manger Panel

Meeting Notes from the September 2018 San Francisco STC Meeting: “Hiring Panel: Ask Hiring Managers your Questions”


by Frank Welsch and Karen Schwarze


At the September 19, 2018 meeting of the San Francisco STC chapters, technical communicators had the fortune of hearing first-hand from a panel of hiring managers and recruiters who volunteered to answer questions on the minds of technical writers. The panel participants were:

* Andrew Brown, Director, Technical Documentation at Splunk.

* Michael Rutledge, Staff Engineer at Scality.

* Helena Jerney, Information by Design.

* Andrew Davis, Synergistech Communications, technical content developer recruiting.

Cheryl Solis, senior manager of Information Development, was scheduled as a panel member but could not attend due to an injury.

David Hulbert, President of the San Francisco STC Chapter, asked the following questions. In the conversation that ensued, the audience not only got answers to Hulbert’s questions but also gained insight into other areas of the hiring process.

Do you control the budget for hiring technical writers?

The consensus of the panel seemed to be that the compensation package range for technical writers is controlled by other groups in the company.

Michael Rutledge said that he does not control the compensation budget of technical writers that he hires. He estimated that hired writers in the Bay Area earn 90-95% of the average salary for comparable positions as reported on He finds that he can stretch the hiring budget by hiring writers more economically in EMEA countries.

Helena Jerney offered up her experience as well. While she does not have direct control over the hiring budget, she can influence the amount.

Does a bachelor’s degree or professional certification make an employee a better worker?

The panel unilaterally expressed the opinion that a degree or certificate is not necessarily a barometer of how well an employee performs.

What can you say about resumes that you reject?

This question evoked a chorus of opinions stating that a candidate should demonstrate interest in the company and the job role. And the resume should reflect the candidate’s research into the company and job description.

Jerney said the obvious: A technical writer resume that shows poor attention to spelling and grammar is an automatic turn-off. She also observed that if the resume does not demonstrate direct experience in the qualifications posted in a job description, the cover letter should convince the hiring manager that the candidate has sincere interest in the position

Andrew Brown expressed his opinion that a cover letter should accompany a technical writer resume when a candidate applies for a position. A good cover letter is a natural complement to the resume of a technical writer as the letter conveys communication skills that are part and parcel of the technical communicator role.

For Rutledge, the cover letter and resume as a package should demonstrate that a job candidate has done some research to be generally acquainted with the company and the job opening.

Do keywords in a resume play an important role in the hiring process?

Rutledge thought it was more effective to tailor the resume to a specific job opening than to concentrate on matching keywords.

Do you ever let an employee work remotely 100% of the time?

Everyone on the panel said yes—with a qualification: the speakers don’t let new hires work remotely from the outset. The panel expressed the need for new employees to work onsite for a while to build trust with the company before telecommuting.

But once a technical writer has established their credentials and working relationship, the managers seemed enthusiastic to let an employee work offsite. In fact, it was voiced that in some cases remote employees were working too many hours!

Jerney also noted, “99% of the time I get outstanding results from employees who formulate a flex-time arrangement.”

What non-technical traits do you look for in a job candidate?

The panel concurred that passion for technical writing and inherent curiosity about the subject matter are crucial traits.

Andrew Davis recommended that a technical writer could demonstrate passion for technical writing by documenting an open-source technology that lacks information deliverables.

What are your favorite interview questions?

One of Brown’s favorite questions is “How do you define success in a technical documentation project?” And he wants to hear the word “user” in the answer.

Brown and other panel members also expect the candidate to interview them as much as they interview the candidate. The best interviews involve a 2-way dialogue. Brown mentioned that he is particularly impressed when the candidate ends the interview with the question “Was there an interview question that I should have asked?”

Other Words of Wisdom

The discussion among the panel spontaneously segued to other issues about the technical writing hiring process. These “digressions” provided candid tips for writers who are applying for work:

  • Ask for a salary above the range that you are comfortable with. When the company comes back to you with a lower salary counteroffer, you can negotiate a more realistic salary and show to the hiring manager that you are accommodating.
  • The afternoon is generally a better time to interview than first thing in the morning. During the morning, people on the hiring team often are distracted by a barrage of emails that have come in overnight.
  • Hiring managers prefer resumes that have been submitted through internal referrals from current employees. Generally, hires who come through internal referrals work out better.



Seeking Lecturer for Technical Documentation Course at SF State

The Technical and Professional Writing program at San Francisco State University seeks a lecturer for the course listed below. The opening is for fall semester 2018 only, but repeat employment is a possibility. A link to the full job posting, as well as more information about the benefits of working for SF State’s TPW program, is available here.
– – – – – – – – – – – – –

TPW 480: Writing Technical Documentation

Online course
The Technical & Professional Writing program at San Francisco State University invites interested professionals to share their expertise with our students. We are recruiting a Lecturer to teach an upper-division course, TPW 480: Writing Technical Documentation, during fall semester 2018.
The course is delivered fully online. It teaches students to design and develop standard types of technical documentation such as project plans, process descriptions, procedures, tutorials, and usability tests.

Renew or Start an STC Membership Today

It’s membership season at the STC!

Renew or start an STC membership to get access to:

  • best-in-class technical communication education
  • publications
  • CPTC Certification
  • career development
  • professional networking opportunities
  • other exclusive member benefits

When you purchase a membership, don’t forget to add the San Francisco Chapter as your chapter membership. Your support allows us to continue offering monthly meetings to our community.

You can only purchase an STC and chapter membership at

UX Awards: Enter Now!

Society for Technical Communication San Francisco Chapter is proud supporter of the 6th UX Awards, the top independent global awards for UX that honors exceptional people, products, process in digital experience. 2017 judges are senior design and UX executives from Cooper, Intel, LG, IDEO, Oculus, PayPal, Amazon, Smart Design, X (Google X), Phillips and more.

Submit your best work for this year’s event by 7/31/17 (6/15 early bird) at: (and use our code TECH for 15%% off).


The UX Awards celebrate and showcase the most innovative people, products, and processes of next-generation digital product, customer experience, interaction, service, integrated industrial-digital and experience design. We inspire technologists to create human-centered products that solve real problems.

The 6th UX Awards Summit will be in Palo Alto, CA November 8-9 2017. Anyone can enter any digitally-focused product, experience or service from May 25-July 31, 2017. Our 2017 theme, “The Future of UX”, focuses on celebrating outstanding UX for both current and emerging technologies, environments and societal challenges.

Field Trip to the Bay Model: June 3

Mark you calendars! All Bay Area STC Chapters are organizing a trip to the Bay Model. The excursion is sponsored by Berkeley and Eastbay Chapters of the STC. It is open to all STC members and friends, but please RSVP, as the size of the guided tour is limited.

When: Saturday, June 3, 2017, 2:00 pm to 5:00. Guided tour at 3:00 pm.

Where: Bay Model in Sausalito, CA

Bay Model Visitor Center
2100 Bridgeway

What: Tour of the Bay Model Visitor Center, which is a fully accessible education center administered by the U.S. Army Corps of Engineers which hosts a working hydraulic model of the San Francisco Bay and Sacramento – San Joaquin River Delta System.

Price: Free admission and parking.

How to Register: Please RSVP to Patrick Lufkin,

Full Announcement

Visit one of the Bay Area’s hidden treasures, the San Francisco Bay Model in Sausalito.

The Bay Model is a three dimensional, working model capable of simulating the complex tides, currents, and flows of the San Francisco Bay and Delta. Built in 1957 by the U.S. Corps of Engineers to study the region’s water flows, the facility’s research played an important part in our economy, and in efforts to save the Bay.

With its core mission since transferred to computers, the facility now educates the public on the natural and cultural history of the Bay and its watershed.

About the size of two football fields, the facility is a marvel. Pumps move the tides up and down on a regular cycle. The model is fully labeled and detailed. You can circumnavigate the bay and delta, walk over parts of it on bridges, and become aware of out-of-the-way places most of us have never visited.

To educate and inform, the facility marshals a full range of technical communication techniques. It uses dioramas, posters, signage, and more. There is a small theatre. There are audio stations with head phones. And of course, there is the Model itself, and the guided tour we will be taking.

There is also a room dedicated to ship building on the Bay during the “Rosie the Riveter” period of WWII.

The Bay Model is easily accessed from either the Richmond or the Golden Gate Bridge.


Leveraging Structured Authoring/DITA Techniques When All You Have are Unstructured Tools

For the January 18, 2017, meeting, Monique Semp gave a presentation called “Leveraging Structured Authoring/DITA Techniques When All You Have are Unstructured Tools.” This meeting summary was written by Pete Babb.

The limitations of DITA

Good structured writing has consistency in everything from the order of information to use of terminology to citation style. DITA is a particularly rigid form of structured writing that’s great for content reuse and translation, but because it’s so narrowly focused, it’s not always the best choice for a given writing task and often can be a solution in search of a problem.

DITA tools enforce consistency by making users to comply with certain formats (think of the Task, Concept, and Reference topics), but that same sense of structure can be found in unstructured tools like Microsoft Word, Adobe FrameMaker, and MadCap Flare. This is important because most companies today are not likely to pay for dedicated DITA tools like oXygen.

There are tradeoffs between structured and unstructured writing tools. Structured tools make content reuse, semantic styling, and version control easier, but all of these can be done without them. With diligence and some familiarity with advanced features (and hopefully a good editorial team behind you), you can gain the advantages of structured writing.

These 8 basic steps will help you bring structured writing principles to unstructured tools.

How to apply structure

Step 1: Write topics, not books or chapters
Structured writing is topic-focused, with each document addressing a single topic. These pieces can then be collated into a master document, like a ditamap does with individual DITA docs. In FrameMaker, you’d create a .book file, and then for each “chapter,” add a folder to the .book file. In Microsoft Word, create separate files for every topic and put them in a master doc. Flare, meanwhile, is already set up for topic-based writing, so structure is inherent in the content.

Step 1b: Use consistent styling
No matter what tool you work with, you’ll want to adhere to file naming conventions (“R” for reference, e.g.) and make good templates. This way, all your writing will be consistent, and your files will be easy to find and sort.

Step 2: Write a short description (<shortdesc>)
The <shortdesc> tag in DITA provides an abstract highlighting what will be in the rest of the topic. This can also be accomplished by creating a shortdesc paragraph type in FrameMaker or Word. In Flare, you’ll want to create a CSS class for this paragraph type.

Step 3: Reuse content
Topics can easily be reused in DITA by adding them to multiple ditamaps. This function can be roughly replicated with unstructured tools, but you’ll need to manually track topic use. In FrameMaker, each topic should be a standalone .fm file, which can then be imported as a text insert when needed. In Word, you’ll want to use Master docs, or try tools like, to help with reuse. The ability for topics to be included in multiple projects is a standard feature in Flare.

Step 3b: Reusing fragments instead of whole topics
Reusing pieces of a topic instead of the entire topic will typically be done through the use of variables. In FrameMaker, you would customize your system variables, while in Word, you’d use AutoText to define fragments, then use the AutoText field code to enable easy doc updates.

Step 3c: Reuse content, but change it just a little
If you need to slightly change content–for example, “We want to reuse this list of instructions, but we need to change step 3”–you may have to use some workarounds. FrameMaker includes conditional text management, which allows for reuse with changes, and Flare has a conditional text feature that lets you tag content for reuse at multiple levels, including small snippets. In Word, though, you can try to use hidden text as a substitute, but you may need to use third-party tools like SmartDocs or Clio to do it well.

Step 4: Style content sematically
As with DITA, it’s best to avoid hard-coding content style like boldface or italic in unstructured tools and instead create character and paragraph styles: <bold>, <cite>, <uicontrol>, etc. In Flare, you’ll need to create CSS classes to apply styles.

Step 5: Standardize navigation aids
DITA will automatically add navigation text based on tags (i.e. adding “What to do next:” before a <postreq> tag). With unstructured tools, you’ll need to create paragraph styles to automatically include such lead-ins. You can then mimic the mandatory styling of DITA by using these styles in templates.

Step 6: Add metadata
Most unstructured tools have good metadata capabilities. FrameMaker supports XMP (Extensible Metadata Platform), and Flare has built-in metadata controls for topic types, custom file tags, and other user-created and XHTML-compliant tagging. In Word, you’ll need to configure the document’s properties to add metadata.

Step 7: Publish to multiple channels
While DITA doesn’t give great PDFs, FrameMaker and Word do. You just need a good designer and good templates, and you can easily output high-quality PDFs. Flare has good built-in PDF capability as well, but it’s more limited than that of FrameMaker or Word.

Step 7b: Publish in non-PDF formats
FrameMaker and Flare also excel at non-PDF outputs, such as HTML and EPUB. Word, however, will probably require a third-party tool like WebWorks ePublishing to do acceptable non-PDF documents.

Step 8: Version control
DITA allows for version control just like software code, and DITA tools often feature integrations with version control systems like Subversion. But FrameMaker and Word lack these capabilities, so you’ll likely have to do binary files by saving as .txt and manually handling diffs. Fortunately, Flare has built-in support for Git and Subversion, so it makes version control easy.

For more detailed program-specific tips and examples on how to do each step, see the dek at Monique’s LinkedIn page:

Happy New Year: Some Exciting Changes to Our Monthly Meetings!

Happy 2017 technical communicators!

With the new year comes a few exciting changes for the SF Chapter.

First of all, all of our monthly meetings are now free for everyone. Whether you are an STC member or not, you get in for free. This also means that we won’t be offering student discounts or free meeting coupons. It’s free coupons for everyone.

Now, why still become a STC member or join the SF Chapter through the STC? Because your generosity is how we can offer free meetings for everyone. That $25 due goes a long way to provide sandwiches for guest, keep this website running, and pay for our PO box. We sincerely hope that you get enough enjoyment and education from our monthly meetings to continue making us your home chapter.

Not an STC member but still want to contribute? We’ll have a tip jar at the meetings, plus a virtual tip jar on our new Meetup page. It’s easier than ever to register for the meeting. You’ll get reminders and get to see who else is attending.

Why register at all if there’s no charge. We use this for the all important sandwich ordering. Plus, since we’re still at the Salesforce office, it makes checking in faster for you.

Here’s wishing you a great year. Hope to see you and catch up in January!

Intern Needed!

NGINX is a fast-growing startup located in San Francisco in the South of Market area (SOMA). We are seeking an intern to work with our Marketing team, contributing to our popular blog at The internship position is paid on an hourly basis.

The ideal candidate for this internship will be:
– A current or recently graduated college student
– Seeking to major in computer science, communications, marketing, or a combination
– A crisp, clear, and concise communicator, in written and spoken communications
– Analytically minded; math skills appreciated
– Aware of search engine optimization (SEO) and how SEO is used in marketing
– Aware of web server technology and how web servers are used in websites and apps such as Amazon, Airbnb, and Uber
– Work experience related to technology development (from startup to Fortune 500)
– Available up to 20 hours a week for next few months, mostly at our offices

Also desirable: High test scores, good grades, print or online publication of your work, and other supporting information relating to the qualifications above.

Writing Code Samples for API Documentation

For the September 21, 2016, meeting, Joe Malin discussed writing code samples for API documentation. This meeting summary was written by Michelle Mills.

When we write API documentation our audience always already has a basic understanding:

  • Millennials have used computers since high school; all are computer literate
  • Diverse professionals (accountants, graphic designers, etc) probably know what they are and want to utilize them
  • All users are therefore also developers

Code samples are important

  • Developers want to be able to copy code from documentation
  • Code samples are fairly complete apps (not a description or tutorial)
  • Shorter is usually better (long is often too specific; specifics can be addressed in footnotes if necessary)
  • Inference links outside your organization are discouraged (continuity and accuracy cannot be guaranteed)

Your documentation should:

  • Illustrate patterns and tasks
  • Promote copy/paste
  • Be simple
  • Be applicable to “real life” issues
  • Be high quality:
    • Solves real-world problems
    • Uses programming language standards
    • Provides working samples

What is a pattern or task in API documentation? Examples include:

  • Security (OAUTH identification)
  • CRUD (create, report, update delete)
  • UI, including:
    • App navigation
    • Enhanced effects (animations, carousels)
    • Responsive UI

Specific example: Good pattern/bad writing

From Salesforce SOAP API documentation API (freely available); used to convert a “lead”:

public String[] conv() {
     String[] result = new String[4]; 
     try {
           Lead[] x = new Lead[2]; 
           Lead y = new Lead(); 
           y.setPhone(“(707) 555-0328");
           x[0] = y;
           Lead z = new Lead();
           x[1] = z; 
           SaveResult[] retr = connection.create(x);
} catch (ConnectionException e) }

Some problems:

  • No comments
  • Nonspecific variable names (i.e. x)
  • Shortened string variable names (conv instead of convert or convertLead)
  • Where did ConnectionException come from?

Code corrections for above example:

// Convert a Lead into an Account and a Contact
// Based on Enterprise WSDL setup
public String[] convertLeadRecords() {
      String[] results = new String[4];
      EnterpriseConnection myConnect; 
      try {
           Lead[] Leads = new Lead[2];
                Lead[0] = new Lead(); 
           Lead[1] = new Lead();
           SaveResult[] results = myConnect.create(Leads);
      } catch (ConnectionException connectExcept) }

Common coding errors that are easy to catch include:

  • Poor naming conventions:
    • using foo or x
    • Non-standard naming conventions, such as:
public class Myclass {
  • Non-standard indentation, such as
for (int i = 0; i < 10; i++) 
  • Forgetting the variable’s name, such as:
var destSite = ‘’
response = sendRequest(destURL);
  • Accidental misuse of = and ==

Always test your code sample to be sure it works!

Good code samples include:

  • Samples that adhere to the styleguide
    • Use company-standard icons
    • Data input labels below input
    • Test on small devices
  • Coding guideline examples:
    • Mutable variable: mIncomingEvent
    • Constant: SECONDS_PER_MINUTE
    • Package names: com.example.sampleapp
  • Commenting guidelines and examples:
    • Use line or block, not both
    • Add to the sense of the code – don’t just restate the obvious
    • Add licensing info to every file (tech writers need to understand licensing and/or ask manager or legal.)

Take a piece of raw code, and apply your style, commenting, and coding guidelines. You can also generate snippets or gists from a raw code example.

Resources for licensing information:

  • Github repositories

Resources for code examples: