Session 4 Notes – TC Camp 2019

TRANSCRIPTIONS ARE IN PROGRESS.

#1 (API) Using JavaScript libraries like jQuery or Node.js

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#2 Lightweight DITA / DITA future

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#3 Markdown for Techcomm

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#4 Freelancing

Scribe: John Perry

Notes:

  • Know your audience
  • Network with power partners: people who know the people who need your services but don’t do what you do: eg. graphic designers, commercial photographers, are good power partners for writers.
  • Cold calling:
    • Don’t call tech pubs, call a project manager, product mgr, program manager
    • Social engineering: contact sales group and ask for the person in another group (eg project mgt) that you actually want to contact; they’ll transfer your call.
  • Social media presence:
    • blog, facebook, LinkedIn, twitter, facebook
    • professional organizations
    • A youtube channel with over 2000 subscribers gets monetized: monthly royalties
    • blogging
  • Self-publish
    • Cafe press; Lulu – can lead to sales of your book on Amazon
    • Zazzle: photo, drawings, paintings, books on cafe press
    • networking: time intensive not necessarily a lot of return
      • avoid networking that targets general population
      • network of professional business consultants that target Fortune 50
  • Advertising
  • Conferences
    • horizontal network at technology conferences
    • business printers
  • LI Profinder: respond quickly; opportunities close after only a few responses are posted
  • Mom Project: small projects (2 wks part time) to longer term (3 mo) to full time. Meant for moms returning to workforce but you don’t HAVE to be a Mom.
  • Writers Market book:
    • 3000-4000 markets for writers; magazines, newspapers, etc.
    • Uses $ symbol to rate pay of various employers from one $ to three $$$
  • Query letters: how you submit a freelance article to a publication
    • typically for one article but one article can lead to long term work
    • multiple submissions
      • sending more than one query letter a month
      • it’s frowned upon but you can do it anyway
    • evergreen article: general enough to be republished in different magazines
    • Magazines may take two years to respond to your query and 5-6 months to pay you,
    • secondary rights: mention that someone else has published your article
    • To see if magazine takes freelancers look in the masthead for “contributing editor”
  • Contract tech writing
    • last April new law in CA has made 1099 harder to get
    • linksv – venture funded startups:
      • where to find potential cold-call candidates
      • these companies are not going to be on indeed or glassdoor
  • If you post your resume on sites like linked in, glassdoor, monster, dice, you will get spammed a LOT
  • Most Bay Area TW jobs prefer onsite W2 but if you have expertise they need you may have some leverage

#5 Ways to simplify complexity

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#6 Amphitheater

There were no sessions in the Amphitheater during this time slot

Session 3 Notes – TC Camp 2019

TRANSCRIPTIONS ARE IN PROGRESS.

#1 (API) API Documentation Practices

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#2 Content Reuse Mechanisms for DITA

Description:

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.

Notes:

    null
  • 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.

Notes:

  • 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

Description:

  • 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

Notes:

  • 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

DO’S:

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

DONT:

  • 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

Description:

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

Notes:

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

AI/chatbots

  • 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 stc-berkeley.org
  • 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!

Session 2 Notes – TC Camp 2019

TRANSCRIPTIONS ARE IN PROGRESS.

#1 (API) Design Patterns for API Docs

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#2 Communicating with SMEs

  • Let’s continue discussing some of the topics regarding communication best practices from the morning workshop.

Scribe: Samantha Munroe

Top takeaways:

    null
  • Look up John Collins (Atlassian)
  • Get creative on working with far-flung team members
  • Experiment with document review tracking software

Notes:

Using all methods of communication with SMEs (JIRA, email, etc.)—but it’s good to assemble a project team at the start of each project to identify each project component and its end-user benefit, then backtrack to link each benefit to the development steps req’d to achieve them

John Collins has an Atlassian playbook for content design—on’s on LinkedIn—he also has a blog on medium.com

Working w/ geographically dispersed teams—delays in receiving answers can be problematic—try using Slack channels to directly ask developers/engineers questions—UTrack can also be helpful—disk bucket (sp?)

Establish hierarchies of SME reviews but watch for SME’s tendency to overstep their roles—don’t let them steamroll your tech writers (and be diplomatic but don’t worry TOO MUCH about PhDs’s egos)

How to establish hierarchies: Educate SMEs re: style guide, how to register bugs/changes, etc.—let internal groups know about your processes/standards.

In terms of tracking edits, MS Word is pretty ubiquitous and can do track changes—others use SDL’s collaborative review feature (but if SMEs aren’t familiar with the platform, they may resist)

  • Document Review Tracker (DRT) software can be helpful if you can enforce engagement—lots of different software brands

Agile project mgmt tends to make user manual development VERY secondary—efforts to make manual dev. Concurrent fall flat

Google tracks bugs via a “live,” constantly updated priority list—so errors are tracked in order of priority—the docs team assesses each problem against the prev. project priorities and adjusts as necessary

Never underestimate the power of socializing w/SMEs (or bringing donusts)—acknowledge help that you receive in team/group meetings—OR send a “thank you” email & Cc: their boss 🙂 — you can also incentivize feedback by using websites like Bonusly (bonus.ly)—OR try something like 15Five

Networking + socializing is very important in less structured work environments (eg, startups)—there are also advantages to being “deployed” (assigned to sit with the engineers you write docs for)


#3 How do you handle PDF vs HTML output issue?

The main types of output are PDF and HTML.  Although some folks consider PDF past its prime, most users still seem to prefer that format over even HTML5.  Why? Is one format sometimes more appropriate than the other? Should we try to convince them to switch to HTML, or should we provide the most user friendly PDF possible?

Scribe: Nathaniel Lim

Top takeaways:

  • Both PDF and HTML are useful.  It depends on:
    • Industry (e.g. Healthcare requires hard copy proof).
    • Age of audience (older folks like PDF’s and books formatting and younger folks like HTLM).
    • Content in which it is read (print, computer monitor, mobile device).
  • Other factors:
    • Beautiful.
    • Cheap.
    • Easy to maintain.

Notes:

  • Is PDF still useful?  It depends upon the industry.  The Healthcare industry requires printed documentation, requiring the use of PDF format.  Links to outside URLs are obo in PDFs. Sometimes PDFs and HTML are published from the same source.  Many people like the book format that PDF provides.
  • Older folks prefer the PDF (book style) form and love the structure as a document.  
  • Younger folks prefer the HTML form.  However, in the far-off future, there is an effort to make PDF more responsive like HTML.
  • The choice of DPF or HTML depends upon the context in which it is read (i.e., print, computer screen, mobile device)
  • When generating an XHTML document to a PDF, it tends to look like it came from an MS Word document.
  • For localization, XHTML includes formatting where as DITA does not.  Thus, it is much less expensive to send structured documents to translators.
  • Consider printing PDF files in landscape format if it is only to be viewed on a computer monitor because most monitors are also set to landscape mode.

#4 Minimalism

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#5 Automating documentation processes

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#6 Amphitheater

Lightning talk: Smart Shiba’s Guide to Image Formats

Presenter: Jessica Parsons

Scribe: WHO?

Top takeaways:

  • ….

Notes: