Session 1 Notes – TC Camp 2018

#1 Chatbots

Discussion of chatbot topics from morning workshop:

  • Where do chatbots and techcomm intersect
  • Is your company considering implementing chatbots?
  • Have you seen or used chatbots “in the wild,” and were they effective?

Scribe: Tonie Flores

Top takeaways:

  • Chatbot gives automatic response to a message.
  • Examples of uses:
    • Gather information interactively rather than via Google email responses.
    • Gather diagnostics.
    • Auto responses to FAQs.
    • From linguistics: Syntax and semantics for training chatbots. * Agent = does the action and * patient = acted upon.
  • Tools: WIT. AI owned by Facebook. Used for testing to provide POC. Requires domain expertise.
  • Content already tagged and cleaned is half the battle.

Notes:

  • Chatbot = automatically responds to my message.
  • Lives on a platform; extension of your  product.
  • Start with live chat to get patterns to automate. That’s when you would use automation.
  • Example: I’m looking for a job in the city.
  • Natural language processing. WIT. AI owned by Facebook. Only (?) for testing to provide POC.
  • Train to detect intents, traits, and value of questions. Requires domain expertise. How many ways can someone ask a question?
  • Getting content, traits, and values is half the battle.
  • Syntax and semantics from linguistics used for training chatbots.
  • Agent = doer; Patient = acted upon.
  • Patrick Bozek – EasyDITA has an example of use of chatbots for documentation.
  • Example of use of chatbot: Conversational ay to gather information. Alternative to Google search results page.
  • Chatbot helps gather diagnostics.
  • (?) Chatfield: A toolkit, quick and cheap.
  • RASA: Open-source…”gotcha”: Facebook  owns your data.
  • Cannot understand sarcasm; for example, So happy I had to wait 10 hours to get this information.

#2 Implementing open source documentation

Description: 

  • Creating documentation for an open-source project differes from creating documentation for proprietary software in these ways:
    • Engaging your community of developers to contribute docs to the project
    • Building your documentation tools to enable collaboration from non-staff contributors
    • Enabling continuous updates through a transparent review process
  • Share your experiences in helping to create docs that are useful for the developer community

Scribe: Wendie Ruano

Notes:

  • “Help wanted on docs”
  • To find out how to contribute: search for tags “help,” “docs,” or similar terms
  • Go to github.com, login/create an account, search for ways to contribute.
  • Your contributions are reviewed, possibly revised, rejected
  • Look for tutorials on the github.com site or (google: github tutorials)
  • Github has user groups and companies have accounts
  • Doing a getting started doc is a major and usually appreciated contribution
  • A good tactic is to comment, say you’re interested, and offer to help with the doc
  • Best to wait for response before wasting time
  • Tools: use Markdown or HTML as a backup
  • Use Jekyl for introductory web site building

#3 Techniques to interview SMEs to get info for the doc

Description:

  • What techniques do you use to get information from SMEs?
  • Sometimes the SMEs are still formulating concepts and reference material in parallel with the writing. Sometimes the information is split across SMEs.
  • Do you have any standard questions or standard ways to organize the information?
  • How do you record this base info ad digest it later?
  • 2 pre-votes and 16 at TC Camp

Scribe: Kevin Hufnagle

Top Takeaways:

  • Do your homework ahead of time.
  • Come up with a game plan.
  • Keep overall project context in mind (beyond specific feature).
  • Understand teammates’ expectations of you, your role, and adjust/change as needed.
  • Repeat back answers to minimize misunderstandings.
  • Encourage SMEs to describe and deliver use cases, caveats, & gotchas.

Notes:

  • Gather specs beforehand?
    • Product managers and software engineers co-write 1-pager design docs.
    • Same physical area as engineers helps. Be available to discuss and overhear developers.
    • If can’t sit co-located, solid design beforehand helps. Also be responsive in IMs & email.
  • Walkthroughs & demos
    • Sometimes TWs encouraged/expected to ‘try it ourselves’.
    • Recording interviews & IMs with SMEs helps in giving yourself 2nd, 3rd chances to understand nuances.
    • Use cases and pitfalls.
  • Up to TW to understand how other pieces in the system work.
    • Consoles tend to be easier to digest and create.
  • Types of questions
    • What-if scenarios
    • How piece fits in with rest of product & work flow.
    • Repeat back your understanding of the answer—resolves misunderstandings
  • Conflicting info?
    • If 2 SMEs have some “report ancestor”(?), reach out to them to discuss strategy.
    • Often the product’s value add and place in work flow story more nuanced than tech itself.
  • Patterns of release
    • As tenure on team increases, can detect and take advantage of similar themes and decisions across multiple releases (“punted [?] features”).
  • Team dynamics – how to interact with SMEs as only TW?
    • Understand and develop teammates’ view of your role.
  • Caution w/ documenting unreleased features.
    • TW serves as glue, sharing info among different teams
  • Digest base info later.
    • Recognize when SME is going down the rabbit hole. Don’t dilute notes!
    • Have a set of questions, general ideas to discuss ahead of time and come up with rough plan of documenting feature – encourages research
    • Mismatches are particularly important.

#4 TechPubs metrics that are meaningful for business / Why do tech writers have such a low perceived value?

Description: Why do tech writers have such a low perceived value? Why are tech writers constantly at the bottom of the IT totem pole? How can they establish greater value to the organization, removing questions about headcount, job reqs to backfill or not, etc., when they arise? In this discussion group, we’ll explore ways to communicate, measure, and track the value added by tech writers in an organization.

Scribe: Gayle Naylor

Top Takeaways:

  • Tech writers need to prove their value by gathering metrics. Here are some of the metrics that were discussed:
    • Page count, number of words, number of docs
    • Customer satisfaction, did doc influence purchase?
    • Topic reuse

Notes:

Most people in the group are starting to gather metrics and some are planning to.

Here are the metrics that companies are using or plan to use:

  • Page count or number of documents.
  • Customer Survey. After downloading a document, the customer is asked these questions: Was it easy to find? Was it clear? Did it help solve their problem?
  • Editor counts mistakes in manuals.
  • Readability. Put manual through Flesch reading test. (higher is better) This is in Word if you enable the feature. Lower grade level = easier to read. One person started using this in September.
  • Editing time.
  • Cycle time-calculating document project from beginning to end. (Track time to develop, time for SME review, etc.) Hours and calendar of time spent.
  • Number of topics touched in CMS. Topics touched ranged from 10% of content changed to 80% of content changed.
  • Create a final map and this starts the clock. Calculate time to release.
    • Cannot account for gaps when SMEs are traveling and are inactive.
  • Track topic reuse. A pdf converted to html is 100% reuse.
  • CMS is not a project management system.
  • Track the number of times specific types of topics are used. (Single-product company.)
  • For RFPs, see how much of the document is new and how much of it is reused.
  • More interesting is reuse of document types-user manual and RFP for example.
  • One company uses a CMS to generate reports to calculate dependencies. It counts how often a topic is reused (“where-used” functionality).
  • Topic reuse vs. other reuse such as legal disclaimers. Consider making these separate topics.
  • How do you measure tech writer performance? How much does the document cost? Reuse is cheaper to produce.
  • Better documentation lowers technical support costs. Lots of companies don’t know what they spend now!
  • Ask customers how much of product cost would you assign to documentation. Did customer use the documentation to make their buying decision?
  • Google Analytics hooked to the doc site (longer sessions and more hits.) Can watch people walk through document site and click to sales site.
  • Editing, writing, formatting tools-bucket the time to measure
  • You get what you measure. What behavior do you want?
  • Here is one approach: total number of points per month based on effort.
    1. Knowledge transfer
    2. Size
    3. Complexity
    4. Media/images

#5 Building an online portfolio

Description:

Hiring managers and recruiters are an impatient lot. They want to assess your writing ability before the phone interview. An online portfolio can make your phone ring faster.

Let’s discuss:

  • What to include in your documentation portfolio
  • Where to host it (Dropbox, LinkedIn, a personal website, GitHub, etc.)
  • When to include proprietary/NDA’d content

Moderator: Andrew Davis

Scribe: Tatyana Perelmuter

Top Takeaways:

  • Portfolio is an expectation of recruiters. (add link in resume/LinkedIn)
  • Problems with using links to Word documents: IP, NDA, copyrights, deprecated documents. Ask permission, add disclaimer, search and replace product name.
  • Publish on LinkedIn, GitHub, Writer Residence
  • Static web site generator. Host with Square Space, AWS
  • Make a copy of publicly available documents to send if deprecated

Notes:

  • Online portfolios are expected
  • What to include and where to post it?
  • Explaining what you’ve done on employer web site is difficult
  • How to deal with links to publicly available documents that has been removed?
  • Legally you are not permitted to post copyrighted documents that you wrote for another company on your web site
  • Most people are flexible
  • You can explain why document written a certain way such as impossible deadline
  • GitHub can take all document formats
  • Keep you online presence concise
  • gohugo.io-static web site generator. Link to living documents you’ve written on other sites
  • Include disclaimer explaining the why and how, and the tools to create document (To protect your IP). Edit open source documents to showcase it
  • Cannot freely use documents that you wrote for a company that no longer exists.

#6 Your favorite authoring tools (and why)

Description:

  • FrameMaker, Arbortext, MadCap, Author-It, XMetaL, Oxygen, Word, RoboHelp, wikis, etc.
  • There are quite a few toolchains for people to make technical documentation. Which tools are the best for which situations? This would be a round table discussion with input from all attendees on the capability of familiar tools. The goal would e to map out which tools are frequently used together (identify toolchains) and which common toolchains tend to be used in which situations.

Scribe: Dan Littman

Top takeaways:

  • Tools need to talk to each other better.
  • People need to plan for the inevitable move to structure.

Notes:

  • Google Docs – cloud feature.
  • Adobe FrameMaker won’t be cloud-based any time soon.
  • Use X – what Y do you use with it?
  • From PDF to (?) not efficient.
  • Frame has no CMS, and can’t put it in Git or anything like that .
  • Structured refers to using a content model. i.e. the party to (?)
  • Author-It is structured but doesn’t use XML, so it is trapped  in that app — it is a binary, whereas XML ties (?) doc parts.
  • A contract with Boeing and a lavatory company to use a specific doc model to describe lavatories (?), so docs can merge into Boeing’s larger documentation set (or -?-).
  • Paligu (?) – she found it is the only tool that met all the requirements for the project.
  • People who converted PDF to Word and then edited it.
  • Frame – The master page wasn’t able to accommodate different content and formatting she wanted.
  • Frame doesn’t have the freedom of a DTP tool.
  • Frame – Tables are excellent; the best part.
  • User voice support tool – knowledge base.
  • Confluence – wiki tool, for knowledge base.
  • XMetaL – ideal client? He doesn’t really have one, but more people need to use structure.
  • In multiple docs, trying to figure out how to avoid duplication…is causing teams to become siloed because it’s too hard to show it all to potential.
  • Oxygen or XMetaL – Oxygen has lots of new features; but can be overwhelming (more for XML developers). XMetaL is easier to use.
  • XMetaL is a desktop tool, not cloud, but integrates with XML-based CMS – integrate to the repository of the content manager.
  • Now Frame can output good HTML – not like older versions that trashed it.
  • It’s really the habits of the writer – if people use styles consistently (in Word, for example), it’s easier to move to structure