Session 3 Notes – TC Camp 2019


#1 (API) API Documentation Practices

  • What was written on the original topic used in the voting?

Scribe: WHO?

Top takeaways:

  • ….


#2 Content Reuse Mechanisms for DITA


A big selling point for DITA is content reuse/single sourcing. Managers look at reuse as a means to justify migration to DITA.

  • What are the different ways to reuse content in DITA?
  • How is it done mechanically (conrefs, keys, etc.)?
  • How successful was it?
  • How do you measure the reuse?

Scribe: Bruce Faithwick

Top takeaways:

  • Topic replication and versioning using mapping is huge benefit
  • Very helpful for product iteration and versioning
  • Helpful to reduce cost and time for content localization, high # of products and repeat publication
  • Output of multiple documents through one FrameMaker template saves time: ie, Java API & Visual Basic API through same template
  • Care in managing content in data warehouse or library required.


  • DITA offers topic replication in two or more maps. You can have custom DITA values placed into topics. Reuse from a central location. (Data warehouse) (Libraries)
    • Reuse notes passages or paragraphs
    • Be careful if reuse of linguistic use, better to keep it as passages such as short descriptions
  • Issue is DITA implementation without consultation with writers. Training for DITA is key  to writer success
  • DITA is a standard and not a tool, therefore two DITA implementations are not compatible
  • Issue is integrating legacy documents into DITA. Best practice is write to DITA
  • Moving forward.
  • Success:
    • Two documents created in DITA using FrameMaker
    • API #1 Java
    • API #2 Visual Basic
    • Both content flowed into same FrameMaker template and to output to PDF
  • Success:
    • Publish to internal & external readers
    • Key referencing: Drop in another map to point to different content
    • How to measure reuse?
    • Compare publish vs authored?
    • How much time do you save?
    • How much are you saving in localization
    • Compare actual before and after
  • Editing library or data warehouse language needs to be careful as data may be used in ten places and could have unintended consequences
  • Use with localization, repeat publication, & high number of products
  • Very helpful for product iteration and versioning

#3 Using GitHub for Documentation Version Control

  • Explore how writers are using it.  If you are the sole writer, are you creating a new branch for each feature?  How are multiple writers using it? Who merges the pull request?

Scribe: Deepa Iyengar

Top takeaways:

  • Managing multiple versions of source in you repo vs. managing multiple output versions in folders.


  • Difference between Git and GitHub: GitHub is the GUI layer and Git is the core.  Git commands are from the point of view of the Git server.
  • Where should your output go?  It should not be source controlled.  Example: Source is in GitLab, build with Jekyll & place the output in the same folder.  GitLab and GitHub are competitors using the same git engine.
  • Note: The main advantage of GitLab is its opensource nature, which allows you to run GitLab on your own servers. GitLab allows unlimited private repositories for free whereas for GitHub, it is not free. GitLab is newer than GitHub, so naturally it is a little less popular than GitHub.
  • Scenario:  Working on multiple versions of the same document.  When you have to update the current branch with masters, you make the change in the master and pull it to the branch.
  • Feature branch can be worked on, edited, merged or deleted.
  • Git pull request for code review.
  • Git merging is merging feature into master.
  • Git rebasing is more linear.  The feature branch is based on master.
  • How to find the commit report for the last week?
  • Git Tower UI gives a view of activity.  Commit many changes on one commit (equash??) vs. one or small change per commit.
  • If you need to publish all versions, have separate folder for each?

#4 Getting User Feedback


  • What was written on the original topic used in the voting?
  • Are you allowed to talk to your users?
  • How do you know what you write is meeting their needs?
  • Have you found reliable, affordable solutions for getting constructive input from your audience?
  • When you have your users’ attention, what are you key DOs and DON’Ts for interacting with them?

Scribe: Cheryl Smith
Facilitator: Dawn Stevens

Top takeaways:

  • Shared mailbox, feedback, link at bottom
  • User conference – inform people of link
  • Support site – feedback about topics – 1 person that tracks, feature not doing what we thought, tracked in Jira, building metrics
  • Do you respond to Users? Plan!
  • Interaction w/support – open tickets for documentation


  • Some have talked to customers directly
  • Based on surveys – Add specific questions: Where do you go for doc?
  • Customer info – get account rep
  • Standard Operating process user AND writer
  • Development Angel – New major release if customer could not figure it out, I looked in doc to find or consult with developer and then incorporate into doc
  • Usability tests on site
  • Only 20-30% of tech writers talk to customers
  • Ways around: social media, tweet, doc-twitter, underused, facebook
  • Thumbs up/ thumbs down – generally not useful
  • 1:1 usually better
  • Surveys – limited use
  • Usability testing of — can they find it?
  • User Experience Design
  • Support – monthly report: what are they asking? If there, why did they call? If not, can we add it?
  • Google Analytics – supporet site analytics, web analytics; what are users looking at; 100 people looked, 10 opened tickets… assume 90% deflection rate
  • Support responds – how many times do they include link to doc?
  • Sit with support to hear problems, what language they use
  • Work with training – are the trainers referring to doc? What do they hear about doc? Training material has examples which people like


  • Set expectations, 5 min – 5 questions
  • Rewards
  • Salesforce (badges, bragging rights)
  • Be polite
  • Respond
  • Be focused/ targeted
  • Thank
  • Tell them the plan


  • Harass
  • Bluff

There was a picture, with 4 quadrants.

  • Horizontal Scale: User knows it/readily available (left), User doesn’t know (right)
  • Vertical Scale: High Priority (top) , Low Priority (bottom)

Quadrants were as follows:

  • User knows it/readily available + High priority = Cover Your Ass
  • User knows it/readily available + Low priority – Don’t Do it
  • User doesn’t know + High Priority = Document
  • User doesn’t know + Low Priority = Inform

#5 Job Market Stuff / Transitioning into Tech Writing


Let’s discuss the tech comm job market in the Bay area. Is it growing or shrinking? What trends are you seeing with opportunities? Is it all develop API type doc jobs, or are there may other opportunities as well? Where do you go to get the inside scoop on jobs — glassdoor, indeed, or other sources? How do you know which companies are toxic and where are ideal? Are will living in a bubble here? Does the high cost of living offset the terrible housing options? Are the sacrifices of living here worth the tradeoffs? Let’s talk about what makes working in the Bay area unique in tech comm.

Scribe: John Perry

Top takeaways:

  • State of the job market
  • Why/How did you get into tech writing?
  • Where do AI/Chatbots fit in
  • How to transition in
  • What hiring managers want
  • Interview the interviewer


Job Market

  • Andrew (Synergistech):
    • Venture capitalists fear a recession; It all changed last fall to W2 onsite
    • A 1099 gets full hourly pay without benefits but gets more writeoffs
    • A W2 gets less per hour but full benefits and more job security
  • Paul Gustafson (Expert Support):
    • Last Fall began converting 1099s to W2s per the new CA law (core competence)
  • Jeremy Lowell (Docforce): There is a still ton of work, wave of opportunity
    • Explaining things without bias drives sales
    • 36% of traffic to IBM site goes to docs first
    • Simplify complexity to make it understandable
  • Prediction: pendulum will eventually swing back to more 1099 contract work

Why tech writing?

  • Motivations of some of the transitioners
  • sw developer: wanted to combat incomprehensible docs
  • like talking about code more than writing it
  • sw developer: frustration with teaching coding camp
  • Law: fell into it from law policy procedure writing, los alamos regulatory compliance
  • American studies undergrad: wrote a lot of research papers but got uninteresting writing jobs (stuff her boss did not want to do.) Discovered that she dislikes marketing writing and likes accuracy, precision, better pay that tech writing provides.
  • chemist: writing SOPs for pharma, designing forms/formats liked improving UX


  • represent opportunity for tech writers
  • Joe D: just completed a bank AI job writing for data scientist, felt underprepped on statistics content. Deliverables included wiki pages to use machine learning.
  • Dave: Natural Language Processing relies on grammar, syntax and context; important for translation. Writers have this skill set!
  • Another important skill: ability to learn new things quickly

Transitioning in

  • A good recruiter adds value by focusing on fit for both the candidate and the employer.
  • Andrew (Synergistech): managers want to see that you can write , and what you know about their product/audience; they don’t want to teach you. At your interview, you should interview the manager to make sure this job will grow not be just a cog in the wheel. Managers are looking for enthusiasm, demonstrated aptitude, initiative.
  • Paul (Expert Support): hiring criteria have changed in past 10 yrs. Managers used to look at your skills and be willing to teach. Now that’s usually not how it works. Exception: brand new tech that can’t be learned outside.
  • Jeremy (Docforce): the recruiter’s reputation is also part of the vendor relationship. Long term relationship: the relationship outlasts the gig.

What do Hiring Managers Want?

  • STC
  • July 2nd Wed of July hiring manager panel:
  • what are you looking for? Who would you hire?
    • excited ability to learn
  • who would you not hire?

Interview the Interviewer

  • How to sniff out the good longterm relationship vs the “use and lose”?
  • Look at the job description: does it demonstrate understanding of the job?
  • Ask at the interview about the long term expectations
  • See Synergistech website for example questions to ask your interviewer

#6 Ninja Talks

There are no notes from these. Anyone who wanted to could come to this session and try!