Highlights – TC Camp 2018

TC Camp 2018 highlights

The TC Camp Day

Keynote Presentation

Download the slides. PDF.

Video Competition

Two sponsors submitted videos to the TC Camp Bowl 2018. The creativity this year was so high that we had a much closer race than we have ever seen before. In fact, we had one write-in vote for “Simply XMetaL.”

XMetaL (First Place)

This was live. We are waiting on finished video… but for now, here are the annotated slides.

SimplyXML (Second Place)

Write-ups by Attendees

TC Camp was great this year (2018). It’s one of my favorite tech comm events, Liz (@lizfraley), Scott (@saprentice), and their crew do a great job every year. The subject matter is always topical, but still applicable, and the agenda favors conversation over lecture.
~ Patrick Bosek, easyDITA blog (January 2018)

Did you write about your experience?

Thanks to the Volunteers

Thanks to all the volunteers who made TC Camp 2018 happen and a success.

To everyone who volunteered the day of the event at the registration desk, organizing the session matrix, answering questions, helping vendors set up and workshops get organized, and all of the 1001 little things it takes for an event like this to happen:

To everyone who volunteered at to help transcribe the scribe notes, so we could post it all to the web. We’ve tried automated services, but those who are not in our industry tend to guess wrong when it’s hard to read the handwriting. Thanks so much to everyone who helped out:

To the board members who worked to secure fundraising, the venue, the catering, and get all the supplies; who helped find and secure excellent workshop leaders; who volunteered at the event; and who picked up all those little extra tasks without being asked:

Photos from TC Camp 2018

TC Camp 2018 Flickr Gallery

Flickr Album Gallery Powered By: WP Frank

Session 4 Notes – TC Camp 2018

#1 Minimalism

Description: 

  • Let’s continue discussing some of the topics regarding minimalism from the morning workshop.
  • How have you implemented a minimalist approach in your writing?
  • Describe some of the benefits you’ve seen from a minimalist approach
  • Any down-sides to minimalism?

Scribe: Jay Martin

Top Takeaways:

    • Know your user
    • Word of the day: Sacrifice – to satisfy the minimal requirements first used in 1651)

Notes:

  • Dawn Stevens said that the . principles of minimal living are similar to minimal writing
  • Evaluate your space (what do you need)
  • Prioritize what the user can’t live without and choose to focus on personas
  • Remove excess
  • What about edge cases?
  • Don’t ignore core customers. Don’t clutter search results. Let them call tech support
  • A place for everything and everything in it’s place
  • Make it as visible as possible
  • Documentation in the interface means that it isn’t needed in a manual
  • Documentation can be complete if it completely helps the user without including steps they already know
  • Minimalism includes repetition if users need steps (and haven’t seen other pages)
  • Cut topics before translation. In remaining topics, simplify the language.
  • Some audiences want friendly but ambiguous sentences. Some (like aircraft inspectors) need clear and longer.
  • Download the simplified technical english dictionary for examples.
  • Separate old content
  • Last point about minimalism: Keep going back, re-evaluating:
  • How to use a mouse used to be documented.
  • Documentation falls into which quadrant:
    • Unique and unknown VS Already Know it
    • as measured against:
    • No impact of not knowing VS catastrophic not to know

#2 Documentation for the Internet of Things (IoT)

Description: 

  • What is “The Internet of Things” and what sort of docs, internal or customer-facing, might be required?

Scribe: Laurie d’Armien

Top Takeaways:

  • Not just data transfer!
  • Components: sensor, network, analytics, human evaluation, configuration
  • Multi-industry
  • Security!
  • Silly: hairbrush, smart beer can
  • Early big brother

Notes:

  • Not just data transfer! Sensors communicate with network
    1. Installing sensor
    2. Network setup – sensors to equipment to analytics
    3. Data analytics – communication
    4. Human maintenance interaction equipment
  • iPhone is a sensor and output
  • Different user for different docs
  • XML standard for docs
  • Standardized nomenclature
  • Diverse applications

#3 Getting user feedback

Description: 

  • 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 tour users’ attention, what are your key Dos and DON’Ts for interacting with them?

Scribe: Kevin Hufnagle

Top Takeaways:

  • If you can’t talk to your users directly, keep in mind that user liaisons have biased filters
  • If users are investing in attending focus groups and conferences, send them a survey
  • See if tech support team can find answers to callers’ questions in your docs
  • Word your questions carefully in surveys to minimize bias, “other” answers
  • Make sure user feedback efforts are vetted by management

Notes:

  • Can you talk to your users? (1-yes; 3-sometimes; 3-no)
  • Those who cannot talk directly use customer support as liaisons. (That feedback is filtered! They’re not always focusing on feedback that tech writers would find helpful.)
  • Feedback systems are sometimes reliable.
  • Some manuals provide feedback form in the back of print manual (don’t have many responses)
  • “Game changes” when you transition from print to web, but frequent users annoyed by it
  • Best way to provide user satisfaction, according to management
  • Systems DO sometimes lead to enhancements, based on user confusion and misunderstanding
  • “Was this helpful?” link leads to rsponses while staying out of the way for power users
  • Need a full feedback loop (don’t ignore feedback)
  • Some users don’t realize that humans need to deal with responses
  • Gather proactive feedback?
    • Focus groups, talk to product line managers, customer reps
    • Can also ask around internally to get a general sense of doc quality, great for validation!
    • Product investment exercises in-house can indirectly reveal doc needs, too.
  • Docs can also be part of a larger survey sent to many customers (holistic feedback about product). In surveys, word your questions properly to minimize bias “other” answers.
  • Take advantage of user investment.
    • Traveling to company for focus groups
    • Traveling to conferences
    • Augment any surveys being done at those events
  • Doc search feature includes “request revision”
  • Good way to filter inappropriate feedback that you’d receive if you are open source
  • User Dos and DON’Ts
    • DON’T criticize user’s approach to using a feature
    • DO ask users whether their complaints should be escalated to “formal” issues
    • DO offer incentives for feedback
  • What do we, as user customers, want to see with feedback from companies
    • Timely response is helpful
    • Allow us to see status of issue
  • Even if survey results indicate nothing needs to change, validation is great to get.
  • See if tech support team (they are users too!) can find answer in documentation
    • If yes, why did user not check docs first? (Is it easy to find?)
    • If no, should we add that item to our docs/FAQs?
  • Most common tech support call topics == greatest need for documentaiton.
  • When talking to users, good end question is: “Was this helpful? Did we meet your needs?” Chatbots should have that question.
  • Anything that has a digital footprint has analytics, but need to synthesize data properly to draw meaning from it.
  • There’s no standardized tool to create a “was this helpful?” box, but it’s easy enough for dev team to create one for your team.
  • If your docs use DITA, ZoomIn (also FluidTopics, easyDITA, SDL Tridon, etc.) web portal collates feedback data and tags feedback on page-by-page basis.
  • Marketing dept. Is a good resource for creating and distributing surveys.

#4 Future of DITA / Content reuse mechanisms in DITA

Description:

  • The DITA OT is an open-source tool. And it’s an important one. It’s used in all of the commercial DITA publishing tools that I’m aware of.
  • However, it has a small group of people who develop and support it, as opposed to other open source tools with many people contributing.
  • Does this mean it’s a dead-end tool that will shrink and fade with time?
  • Is its use expanding or contracting in companies?

Scribe: Dan Littman

Top Takeaways:

  • DITA will continue to expand and find more users. Tools will probably catch up to make DITA easier to use.

Notes:

  • Hope support base, tools, and users will continue to be viable
  • DITA open toolkit is terrible. It could use Frame, Arbor, Top Leaf
  • The whole point is to use it off the shelf. Why would you specialize? The general DITA lets you do ridiculous things.
  • Can use a tool that lets you control it so other users do what you want them to do.
  • Lightweight DITA: How will it play out? In terms of tools, etc.
  • DITA only supports types of information for technical writing, marketing, and training.
  • And we can use it with HTML.
  • That why DITA was able to expand!
  • Most people switching to DITA came from unstructured Frame or Word.
  • A lot of unstructured data will be connected to structure, either as XML or DITA. So DITA will expand.
  • If investment is made in any of the DITA pieces, you need to have someone involved in implementing and training.
  • Other tools like Confluence and Paligo are being used. Modifying DocBook instead of DITA because it’s simpler.
  • Will Chatbots migrate to a structured format?

#5 Career paths after tech writing

Description: 

  • Silicon Valley’s demands on tech writers lead many to consider other careers
  • Let’s discuss ways we (or tech writers we know) hope to succeed professionally after leaving the doc business
  • Some ideas: project management, “Content writing”, UX, Training, proposal writing, product management, patent writing, engineering, website design, investing, sales, marketing, fiction writing, medicine…

Scribe: Andrew Davis

Top Takeaways:

  • Climb the value chain
  • Find new avenues that companies can monetize
  • Sales training – learning skills of persuasion, meeting needs
  • Use your natural curiosity to learn and grow

Notes:

  • “Where are they now”?
  • Medicine, academic org certifications, investing (list of job titles under desc above)
  • Driven by passion or situation? Could be either.
  • Software dev cycle is never-ending; refurbish/flip a house – the work stays done.
  • Looking for a sustainable role.
  • If your hobby becomes your work, does it become toxic?
  • Recasting your communication skills
  • Are you evolving in your current role?
  • People want to grow; tech writers are naturally curious, important to learn.
  • Last one standing becomes default expert, some opportunities for growth
  • The world is awash with data and not enough people to interpret or communicate it
  • Analytics requires higher-level skills. Can you monetize?
  • When content/tech writing jobs go, they only hire what they can sell.
  • Come out of the shadows, connect with customers. You know you can do better.
  • Sales training is an excellent life skill; skills of persuasion, meeting needs
  • Valued commodities in many eyes
  • Creation of crowd-sourced content
  • Curation of crowd-sourced content
  • Giving back – nonprofit? How can we apply our comm. skills?
  • SBA offers classes in proposal writing.

#6 Writers and product usability

Description:

  • All writers should be involved in product usability.
  • We’re tuned into consistency, identity dovetailing issues, able to create a more usable product.
  • We need to speak louder, and more, and make our case better.

Scribe: Gale Naylor

Top Takeaways:

  • Engineers can’t always see what’s not explained well.
  • Technical writers see inconsistencies and where different areas connect.
  • There are many ways technical writers can be useful. Even our managers may not know how much so. We’ve been able to influence changes in a product. We need to insert ourselves earlier into the process. And get ourselves going on deadlines! There’s not an agreed upon definition for usability. But, it’s about getting users to succeed. And there’s a spectrum of usability.

Notes:

  • We suffer first.
  • We are the guinea pigs. We have to test the application.
  • Barriers
    • Getting involved early enough and convincing other we need to make changes when there’s pressure to ship soon.
    • Have to force yourself into the process. Just go to the meeting!
    • And how your value (for example, bug reports) and become part of the process.
    • Sit near and work near dev engineers.
    • “Monitoring all the Slack channels is part of my job now.” Because things are moving so fast.
    • Documentation-driven development. Start with documenting a feature, how would a user use it (user story) See Readme-driven development article by Tom Preston.
    • We are move attuned to consistency. We can show where there are duplicated. It’s expensive to be me.
    • We’re in a position to point out when areas dovetail. But, there are issues.
    • When consistency is missing in content, users will worry about the product. First impression is the website and docs, which are trusted.
    • Agile fails fast, but you only get one chance at a first impression.
    • Sometimes it’s lots of little things that add up to a bad experience.
    • Feedback on docs is hard to track.
    • Docs cover support issues.
    • When you have time, usability testing is great.
  • Content Usability is Related to Product Usability
    • Have to write your way out of a problem is common. You just have to start your high level view while you’re figuring out the high level view. Sometimes you just have to note what to fix next time.
    • Docs should be integrated, like software is iterated.
    • Introduce designers and devs to good writing and good usability concepts.
  • Definition of Usability
    • Users succeed at what they want to do.
    • Documentation sparks joy. (If not, maybe you need to change it. Trust your gut. Usability is a spectrum where you are always making it better.)
    • Do the hard things first.
    • Get more information than you need right now.

Session 3 Notes – TC Camp 2018

#1 Improving search in technical content / WordPress-SEO

Description:

  • Techniques
  • Tools
  • Who are the users? Internal? External?
  • Personalities, Metadata, Taxonomy, Integrating SEO
  • Let’s continue discussing some of the topics regarding WordPress/SEO from the morning workshop
  • Describe your experience in setting up a WordPress website.
  • If you’ve implemented SEO techniques, were they beneficial?
  • Is WordPress the right platform, or are there better options?

Scribe: Dawn Stevens

Top Takeaways:

  • 2 considerations – Google or onsite – different strategies
    • Google – SEO
      • – title
      • – shortdesc
      • – links
    • Onsite
      • Keywords
      • facets
  • Keyword selection similar to index – need special skills

Notes:

  • Behind firewall, not visible to Google, burden on us
  • Keyword search – how to improve;
  • Faceted search – categorize data; do users use facets
  • Users rather everything and don’t want to overfilter
  • Different mindset from shoppers who do filter
  • SEO – Google ignores keywords – title, shortdesc, metatags, plus other considerations – words appear in body as well, links from other ..
  • On own site – keywords, facets important
  • Penalize word stuffing
  • Companies behind firewalls may be doing themselves a disservice – people come to Google first. Many don’t discriminate where it is coming from.
  • PDF on a firewalled system – have to know where to go, login, find right page, dowload product, search PDF– not an easy process.
  • But fear of competitor.
  • No way to make buying decision if not accessible; doc is a key to purchasing decision
  • Corporate decision about what is facing public
  • Linking strategy is also important (SEO) – quality of who you link to and who links to you…
  • To learn more about SEO – Google publishes guide

#2 Complex doc systems with Markdown and Git / Markdown for techcomm

  • It’s simple to use Markdown and GitHub for a simple set of docs.
    • What if you have a great deal of documentation?
    • What can you expect?
    • Should you even try?
  • Markdown for Techcomm
    • What is Markdown?
    • Is it reasonable to use Markdown for Techcomm?
    • Examples of successful implementations?

Scribe: Bonnie Kim

Top Takeaways:

  • Git
    • Version control mechanism
    • Allows easier collaboration
    • Code-oriented tool
    • Will win points with key audience (developers)
    • Gitmersion.com
  • Markdown
    • Simple language for simple tasks
    • Forces simplification of docs system
    • Limited functionality (bells and whistles) HTML as a fallback language

Notes:

    • What can you expect from using Git?
    • Git is a version control system. GitHub is a content hosting system.
      • Lynda.com
      • Gitmersion.com
      • Static website with Markdown
      • All git commands are from the perspective of the repository, not the user
      • Command line vs GUI (Git Desktop)
        • What are you trying to achieve?
        • Command line powerful
        • GUI easy and visible. Greater control and restrictions on what users can do (and mess up).
    • Developers and teammates happy to help.
    • Five commands: add, status, push, commit, branch
    • Solo or team?
    • Start easy and practice
    • Problems working in GUI → Update issues.
    • Command line sync with developers worth the growing pains.
    • Best practices for working in a team.
      • Well-defined workflow, SOP
      • Have the most updated copy.
      • Git is line-based track changes, not file-based.
      • Dedicated Git administrator.
      • Document everything
      • Reference docs for SOPs
    • Git is shoehorned: Not actually a doc tool but written in the user’s native environment.
    • Between push and commit, there is designated review.
    • Preview before you push. Staging platform.
      • Running local server for seeing graphical representation.
  • Markdown
    • Good for simple docs
    • Complex tables are difficult
    • Resort to HTML hybrid
    • HTML + PDF difficult export
    • Not quite strict enough.
    • Text/doc maintenance is painful
    • Simple, procedural, concepts for devs
    • Very simple procedures

#3  Instructional design for tech writers / eLearning and the role of documentation

Description: 

  • There’s often a lot of overlap between “training” and “documentation”.
  • Are they the same thing?
  • Can one be substituted for the other?
  • Should corporate training and tech pubs documents be merged? If so then who’s in charge?
  • Which is more advantageous from a corporate perspective?
  • For writers seeking to apply for ID positions, what do we need to know first and foremost?
  • As eLearning becomes more mainstream, what role can/does documentation play?
  • What changes are necessary to doc structure, media, and format to make synergy and reuse possible?

Scribe: William

Top Takeaways:

  • Tech Writers as knowledge transfer
  • Linking content through structured
  • Design thinking

Notes:

  • What is ID? IA for learning content.
  • Most cos, background for docs is learning goals.
  • Knowledge transfer → Learning objectives, assessment, certification
  • Tech writers are usually in KT, but learning is downstream. We should connect at LOs.
  • TWs are topic and task-based. Should connect with LOs if LOs are similar to TW topics.
  • What do TWs and trainers have in common? Often they do not communicate.
  • Training is now web-based, LMS, etc.
  • Are writers writing for documentation or instruction?
  • Formal learning taxonomy: Blooms learning taxo – You can remember. Los w/more
  • Formal processes are using the learning taxo to create through to cert.
  • How would an instructor use doc to create instructional material?
    • Learning theory
    • Trend: fewer and fewer graphics in documentation
    • The content is not for the same purpose, but there is stuff that is duplicated.
  • One example: reuse task in docs and learning.
  • Trainers may know more about learning theory, insight into the needs of the learners.
  • Tech writers: Trainers could add links to training materials.
  • Tasks/procedures are written up w/o context. Could supply the same steps written in exercises with context related to different business verticals.
  • Help could have button linked to tutorials.
  • How about testing use cases? Usually no time.
  • Design thinking: Necessarily interacting with end-user.
    • ID needs prototype, testing, feedback.
  • Very little tech writing is involved in social media.
  • Agile: 1 dev cycle, next sprint is when docs catch up.
  • When use cases are being discussed, TC should get in.
  • Product management leads.

#4 Securing remote tech writing work

Description:

  • How can you persuade a prospective client or employer to let you work remotely?
  • Which kinds of teams, organizations, and industries are more (and less) amenable to letting tech writers work offsite?

Scribe: Alisa Bonsignore

Top Takeaways:

  • Opportunities for remote working are limited
  • Companies are struggling to find onsite workers, but they’re not budging (on allowing remote work)
  • Many cost/emotional/environmental benefits to remote work.
  • Sell yourself as a resource, not a cog

Notes:

  • Mixed groups between all offsite and mixed onsite/offsite structure.
  • Major traffic avoidance.
  • Home office limits distractions, pressures of office politics, and fear of office dogs.
  • Clients like to micromanage, have been burned by remote workers in the past.
  • How do companies integrate remote workers & workers in other offices (with onsite employees)?
    • Should be a similar situation for remote & other offices
    • Video conferences, etc.
  • Recruiters try to encourage hiring managers to consider remote workers. Suggest working onsite for x months with possibility of transition to remote.
  • Small companies are more flexible than large. Open source companies are generally more flexible. Not seen with larger companies.
  • Some participants are finding it harder and harder to find remote work opportunities.
  • When the job market is tight, it’s harder for them to find onsite workers and they have to extend to remote workers.
  • And yet onsite is costly for businesses: lighting, HVAC, real estate.
  • Environmentally unfriendly to pump carbon emissions during traffic.
  • Emotionally unfriendly to workers in high-stress commutes.
  • One participant is in-house but works with a remote worker via Skype/Slack just fine.
  • Freelancers have had good experiences with specific project-based work.
  • Another worked ina  virtual business setup with developers based out of the country.
  • It’s hard to fill these jobs, hopefully something will work.
  • Many of us say we actually work more remotely (nights/weekends)
  • You’re selling your problem solving resources, not just another worker.
  • Play hardball.

#5 Tools for documenting REST APIs / Breaking into API documentation

Description: 

  • Attendees who are using tools like Swagger or Postman to help them document HTTP-based APIs can talk about their experiences. Those who are doing ti by hand can hear about the experiences of others
  • The title says REST, but strict adherence to Fielding’s definition of REST is not important for this topic
  • Share experiences about how you got into documenting APIs
    • Your programming experience (if any)
    • The language used, format, tools, etc.
    • Tips for getting into this field

Notes:

This table had no participants, the topic having already been discussed earlier during the day and at the Pre-Camp API workshop. Other topics had higher interest during this slot.


#6 Ways to simplify complexity

Description: 

  • Simplifying complexity is one of the core values tech writers add to a technology organization.
  • But…how exactly do you reduce the complexity of content?
  • What techniques and tools do you employ?
  • From navigation maps to plain language, step-by-step procedures to topic chunking, we employ a variety of techniques.
  • But could we do something more, something truly innovative in order to master this skill?
  • In this discussion group, we’ll examine other ways to approach and simplify complex content.

Scribe: Guy Haas

Top Takeaways:

  • Complicated: many parts and concepts
  • Complex: interactions among parts and concepts
  • We use abstraction
  • We analyze by creating tables, flowcharts, workflow diagrams
  • Trade-offs: complexity can give access to power wherease simplification can foreclose that access

Notes:

  • How to identify user pain points?
  • Go to field engineers – they deal with actual customers
  • Create a grid of options and identify problems
  • Complicated: many parts and concepts
  • Complex: interactions among parts and concepts
  • We use abstraction to simplify
  • Flowcharts & workflow diagrams
  • Complexity can lead to power: mac machine simplifies but makes it hard to go off the beaten path; linux machine leaves things complex but going off the path is in reach
  • Sometimes over-simplifying erodes user confidence (they need to know more about what all it’s doing)
  • Macroview vs microview
  • Consider an 8-step process: on each topic show a high-level view at where we are
  • On-boarding is different from on-going
  • Go for consistency in terminology
  • Adapt tools that enforce consistency of terms
  • How to address the problem of multiple paths?