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: