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:

Session 1 Notes – TC Camp 2019

TRANSCRIPTIONS ARE IN PROGRESS.

#1 (API) Tools for documenting REST APIs

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#2 Managing expectations in big projects

You have stakeholders, and they all want things. Different things. You can do some things; you can’t do others. Beyond the SME relationship, what can we do as technical writers to assert influence and complete big projects as heroes with happy stakeholders?

Scribe: Jill Elhonsali

Top takeaways:

  • 8 hrs/page – industry standard (includes management)
  • Create project plan with milestones – update when slips/changes to schedule
  • Meet with stakeholders; get invited to meetings
  • Public schedule
  • Publicize process – need TechComm
  • Communicate Tech Pubs process – make people understand

Notes:

  • Need to educate managers, amount of time to complete project
  • Need to evaluate time vs resources
  • Eng, marketing, Tech Comm, Mfg, ERD (Eng Req Doc) MRD (Mktg Rq Doc) basis of techdoc
  • Create milestones – per chapter or subset
  • Need to be aware of changes to products – attend scrums, product meetings
  • Project with no deadlines – especially in pharma: create project plan with when you can deliver doc and send to requester. Meet with all stakeholders
  • Public whiteboard with schedule
  • Agile, scrum, scaled agile for enterprise
  • Cloud – fluid
  • Increase visibility – jira approval by techcomm

#3 Exploring Gdocs output


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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#4 Information architecture

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#5 Creating microcontent

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

Scribe: WHO?

Top takeaways:

  • ….

Notes:


#6 Amphitheater

Lightning talk #1: Does Your Conditional Filtering Strategy Scale?

Presenter: Mike Rice

Scribe: Cheryl Smith

Top takeaways:

  • Mike Rice with Jorsek (formerly at Xerox)
  • Using Feature-based Metadata to improve Maintainability
  • Mistakes I made using Conditionalization

Notes:

  • Content can contain compound conditions:
    • Obsolete condition
    • Implicit relationships
  • This becomes messy, creates a bottleneck and causes time expenditure in re-working instead of writing.
  • Solution:
    • Place conflicting items next to each other for analysis (features vs. product is an example)
    • Use Feature-based Metadata

Lightning talk #2: Documentation Tools as a Career

Presenter: Mark Giffin

Scribe: Cheryl Smith

Notes:

  • For a career, it should be a person who enjoys messing with Tools and has an interest in programming.
  • Today the Technical Writer is the tools developer, DITA configuration manager, etc.
  • In Future:
    • IA/Chatbots need more tools expertise
    • Lightweight DITA, Markdown (?)
      • Markup Language
    • Shorthand HTML
      • Static Generator

Session Matrix – TC Camp 2019

This year we had 4 sessions each with 6 different discussions. Every discussion required a scribe and a facilitator. Scribes keep the notes and facilitators keep the conversation focused and make sure that everyone gets a chance to talk.  Both get special merit badges for their extra efforts!

Scribe notes are used during Camp Minimalist, at the end of the day, and saved here so you can access them later. These notes preserve not only what you learned, but give you access to what everyone else learned too!

Notes for each discussion have been posted to the individual session pages.

Workshops

  1. Pre-Camp API Training
  2. Adobe Workshop
  3. Collaboration Workshop
  4. Website Generators Workshop

Unconference Session #1 – Notes

  1. API Track: Tools for documenting REST APIs
  2. Managing Expectations in Big Projects
  3. Exploring Google Docs output
  4. Information architecture
  5. Creating Microcontent
  6. Amphitheater Lightning Talks:
    1. Does your conditional filtering strategy scale?
    2. Documentation Tools as a Career

Unconference Session #2 – Notes

  1. API Track: Design Patterns for API Docs
  2. Communicating with SMEs
  3. How Do You Handle the PDF vs HTML Output Issue
  4. Minimalism
  5. Automating documentation processes
  6. Amphitheater Lightning Talks:
    • Smart Shiba’s Guide to Image Formats

Unconference Session #3 – Notes

  1. API Track: API Documentation Practices
  2. Content Reuse Mechanisms in DITA
  3. Using GitHub for Documentation Version Control
  4. Getting user feedback
  5. Job Market Stuff / Transitioning into Tech Writing
  6. Amphitheater: Ninja Talks

Unconference Session #4 – Notes

  1. API Track: Using JavaScript Libraries Like jQuery or Node.js
  2. Lightweight DITA / DITA Future
  3. Markdown for Techcomm
  4. Ways to Simplify Complexity
  5. Freelancing / Part-time Gigs / Companies to Work for
  6. Ways to simplify complexity