Hot Topic Summit SumUp 2015

A session at Society for Technical Communication (STC) Summit 2015 – Sponsored by TC Camp

When: Wednesday 24th June 2015, 9:45am to 10:30am

Description

Did you miss it? Did you want more details? Do you have un-answered questions? Did you want to throw some ideas around with your peers? Join TC Camp directors for an un-scripted “real-time” discussion with the hot top presenters from the STC Summit. We will break into round-table, small-group discussions where you can delve even deeper into the topics that interest you the most, such as mobile, UX/UI, graphics, API/SDK, and analytics. We end the session with a debrief, sharing highlights so you can leverage your learning with your peers. Space is limited!

Matrix

  1. API
  2. Cloud
  3. Legacy Content
  4. STC

Slides

Notes

Session #1: API

Unavailable

Session #2: Cloud

Unavailable

Session #3: Legacy Content

Unavailable

Session #4: STC

Scribe – Lori Meyer
Facilitator – Mike McAllister

Unaffiliated members

  • How can and should STC can engage unaffiliated members? Many members live too far away from the nearest chapter and cannot attend chapter events. How can we reach and serve them? Use technology wherever possible such as Adobe Connect and Skype. Note: Chapters can obtain an Adobe Connect license at a substantial discount.
  • Issue: Unaffiliated members need to know if a chapter is nearby. Unaffiliated members are often “on their own”. It would be useful for STC to engage unaffiliated members and let them know where nearby chapters are, so that chapter members can invite unaffiliated members to join and become involved.
  • STC needs to provide more information for members to start their own chapters. The CAC has material about leadership resources, which is available on the Leadership Resources page of stc.org. Members interested in starting a chapter need to find information easily if there is an interest in starting new chapters.

Engaging students and encouraging student membership

  • More engagement with colleges and universities can provide potential student members and future members of STC. One person noted that English professors are often resistant to involvement with STC.
  • Best results as far as recruiting STC members seem to come from degree programs that are professional rather than more humanities-driven. More success with professionally oriented programs, so it might be best to go to departments that are focused on professions as opposed to humanities.
  • Technical communication degree programs are often perceived as “liberal arts” programs.
  • It is critical to get younger members involved. Younger professionals are more service-oriented than is perceived. They are not as insular as we think, but their social engagement works differently than that of previous generations. They focus on communities of interest that dissolve as the work is done. They want shorter-term results. They are less trustful of institutions. Ray mentioned the evolving model of SIGS, where the focus is on flexibility. STC as a society needs to make sure it does not limit itself to traditional ways of doing things. Price of membership was an obstacle for one member at first.
  • Value of STC – involvement with chapters and conferences reinforces the value we can add.

TC Camp Gazette #32

TC Camp 2015

Another Great Year! 

by Lori Meyer, TC Camper

Affordable, top-quality workshops…invigorating discussions…exhibits…great prizes…It all added up to another successful TC Camp experience on January 24. Once again, TC Camp combined the best of a formal program and user-driven learning.

This year, we had four well-attended morning workshops. Maxwell Hoffman talked about using the Adobe Technical Communication Suite v5 to produce enriched content for online delivery. Marta Rauch of Oracle discussed jump-starting your mobile projects. Steve Anderson of Salesforce.com provided insights about creating documentation portals. And Tom Johnson of 41st Parameter explored API documentation in changing environments and new technologies.

At midday, we had some game-show fun with Camper’s Feud, where two teams — the Dangling Participles and the Serial Commas — challenged each other to give the best answers to four TC-related questions.

The afternoon unconference included 18 facilitated discussion sessions in three slots, covering a wide range of topics that you voted for in the morning. Examples of popular topics included keeping up with industry trends, HTML5, job search techniques, reuse strategies, and search issues. Then, it was on to Camp Minimialist to hear end-of-day summaries on the afternoon sessions. A representative from each session table was challenged to summarize their session in 60 seconds or less to get a reward. We wrapped up the day with drawings for great prizes, including an iPad Air.

Thanks for another great TC Camp, everyone…and we will see you in 2016!

A Great Big Thank You!

We want to thank our sponsors for making it possible for us to put on this event — at no charge to you!

Camp Extras!

Notes, slides, and pictures posted!

Thanks to our invisible transcribing and posting team workshop pages have been updated with slides and notes.

Check out the main TC Camp 2015 page for links to the individual workshop pages as well as to the Session Matrix. The Session Matrix will show you the full TC Camp 2015 Agenda and have links to the notes for all the sessions.

Here’s a short link to the TC Camp 2015 Page:
http://wp.me/p2GX0I-12d

And Hey! Did you see that the slides from the Mobile workshop by Marta Rauch, Cindy Church, and Gail Chappell were selected as SlideShare Slides of the Day?

Talk to us!

Complete the 2015 TC Camp Survey!

We’re looking ahead to making TC Camp 2016 the best ever! To do that, we need your feedback. If you haven’t completed the TC Camp 2015 survey yet, take a few moments now to do so. Your feedback can help us plan an event that works for YOU!

To take the survey, go tohttps://www.surveymonkey.com/r/TCCamp2015Feedback

TC Camp is on YouTube!

by Scott Prentice, TC CEOWe’ve set up a YouTube channel and started uploading videos from the event in January.

So far we have interviews with a few attendees and most of the sponsors, as well as some other fun items. We have many more videos to upload, socheck back in the coming weeks. If you subscribe to our channel, you’ll be notified when new videos are posted.

If you attended camp this year, you should enjoy reviewing these videos. You will likely see and hear things that you missed while you were busy elsewhere at the event. If you didn’t make it to camp, perhaps these videos will encourage you to join us next year!

Loved TC Camp?

Volunteer in 2016!

A big part of TC Camp’s success is its hardworking and talented volunteers. If you loved TC Camp this year and plan to come back in 2016, consider volunteering! We lots of opportunities to help, so there’s sure to be something that matches your interests and schedule. Here are some examples:

  • planning workshops and finding presenters
  • writing and editing articles for TC Camp Gazette
  • finding sponsors
  • publicizing TC camp through social media
  • greeting and checking in attendees
  • helping set up and serve food
  • counting votes for unconference sessions
  • serving as scribes and facilitators at unconference sessions
  • cleanup at end of day
  • …and more!

If you’d like to volunteer, email us at counselor@tccamp.org and tell us what you’d like to do. Many thanks!

And now for something completely different

Skyliner put together this video about how to get from Narita Airport to Downtown Tokyo super fast. It’s a fantastic example of great documentation – And it’s all in English!

 

Session 3 Summaries – 24 January 2015

Session 3 Topics For Discussion

Generating PDF from DITA

Session Title: Generating PDF from DITA

Scribe: Mark Giffin

Top Takeaways:

  • “It’s Hard”

Notes:

PTC Arbortext makes big PDFs for FM small pdfs when book is graphic-heavy and big, dense graphics involved. Not a large community, few answers

DITA 1.5.3 needs simple changes

It’s Hard.

Teaching topic-based oriented writing

Scribe: Joanna Broadbeck

Top Takeaways:

  • Topic-based authoring: Writing with the goal of describing one thing (topic) as opposed to thinking of a chapter, book ,etc. A topic should be able to stand alone
  • To teach a writer (a) have before and after examples in addition to writing guidelines (b) provide extensive review & guidance on the writer’s first big assignment (c) have writing buddies and referesher training for ongoing reviews to ensure topic writing remains consistent across your team
  • writers tend to write about everything they know, not what reader needs to know
  • understanding and defining TOPIC TYPES is key. Examples of topic types – concept, process/task, reference

Notes:

What is most efficient way to teach a “traditional writer” in a topic-oriented way?

One company moved to DITA we rewrote everything. Developed process for teaching topic-based writing conversion. Everyone read IBM book. Content workshops – writers sat with editor and worked through restructuring the doc. Where is conceptual? Procedural task? etc. Tease apart the bits.

Book: IBM Developing Quality Technical Documentation

What is topic based authoring? Thinking of unit of content as a TOPIC rather than book, chapter, etc. Topics address a single thing. In theory: answer 1 question or explain 1 thing, and not rely on context.

What are stumbling blocks? It’s a mindset change. And there are tool issues.

Topic-based is in pieces, it’s not linear. Topics may be consumed in any order (for example, think of landing on a search result in the “middle” of a “document” – reader should still be able to make sense of it without having read from the start of “the document”)

Links to related content

Collection types and relationship tables is what DITA has to deal with linking to related topics

How to give a new writer training to think of writing in topic style?  (1) have writing guidelines with examples (2) have “before” and “after” examples that have been well reviewed (3) repeat training workshops as new writers are hired; have refresher training too (4) do extensive developmental review and edit with peer and with editor (for new writer on first assignment) (5) have “DITA-buddies” that help coach writers (6) Editors are important!

DITA allows you to define common structures like tables, etc. NOTE: DITA is topic-based, but topic-based is not DITA

Good writing can happen from document down or topic up

Are there qualitative metrics?

One company found docs were better after this: (1) more consistent (2) more accurate because reuse is more accurate, no longer cut and paste (3) topic-based writing created much better, succinct pieces of text that made overall more clear

Mental shifts – linear is often product-focused. Topic-based can be more reader/user-focused. What is user wanting to do?

Writers tend to write everything they know, not what reader wants to read

You can reuse at topic-level

Topic-base writing is easier for writers than learning DITA. DITA should be as hidden as possible to keep writers efficient.

Author-IT is not DITA, but it is topic-based

Process (done by multiple people over time) vs Procedure (done by one person)

Writers need to understand and agree on types of topics (conceptual, process, procedure, reference).

IBM doesn’t do doc plan – but topic names and short description, which is then reviewed with an editor.

Outline is old school, but has a place: introduction, audience, etc. — With Topics, you “Annotate” the outline

“Short description” is an introductory sentence in a topic.

Often you will find a section of traditional writing will end up being multiple topics.

Book: “Author Experience” by Yagodich about going to CMS’s “CM-Ness”

Mobile

Scribe: Tracy Baker

Top Takeaways:

  • We have a lot to learn
  • People consuming content on a mobile device are trying to get something done -> task based content

Notes:

What kinds? Mobile apps, documentation, end-user displayed on mobile device

We talked about what does mobile mean?

Need to learn who or figure out who your customer is

Maybe mobile content is an app?

We discussed the meaning of responsive design

We surmise that mobile users are trying to get something done as opposed to reading to learn

M.*  sites are less desirable than an app or a responsive site.

Review Process

Scribe: Susan Allen

Top Takeaways:

  • Tools support the process
  • PDF reviews are the norm – either via email or shared review
  • There are some other collaborative tools, but no consensus
  • Targeting reviewers is important to get responses
  • One “trick” : send review and schedule a meeting a the deadline: in case they don’t have time for review. Then, say if they review it beforehand, no need for meeting

Notes:

How can we improve the process? Tools support the process. Tools for HTML markup reviews? Convert to Google Docs – Sometimes write it there

PDF reviews – individual emailed copy or shared on server

Google Doc – can control who can change vs control

Code collaborator – code dev tools that support putting comments in PDF – made by Smart Bear – Coders already use it

Enable developers to edit xml

Give more weight to reviewer who is closer to the user

Targeting reviews is important. Highlight points you are not sure of

For large doc – send TOC and ask who should review what

Meeting for first review – walk through. Not finished? How do you want to handle this?

Schedule meeting for deadline. If you can review before, we don’t need meeting.

Oxygen web help with comments (requires database at back end)

Metrics – task tracker for comments

In agile environment – is review plugged into the process? Engineer has no incentive – get it into the process

Using Jira – assign review as a task

“Reviewer Creep” – when reviewers keep getting added. With tracking program, reviewers must be in the tracking program

MadCap makes review tool – does it help? Requires users to install it. “Contributor” also facilitates input flow from other authors. Once installed, works well

DeltaXML tool = change bars

Leave in one grammatical error

User feedback? Quality is often low and frequency is low

Style Guides

Scribe: Heidi Miller

Top Takeaways:

  • Why = Achieve consistency, get answers quickly, users benefit
  • Problems = multiple style guides due to different audiences, cultures, language, resources
  • Recommendations = Pick a basic style guide, have a good reason for exceptions
  • Last Line = People have strong opinions

Notes:

How many have been responsible for style guides? Several, lots of experiences

What goes in? Usage, Mechanics, Style

Recommendation: Steven Pinker’s “A Sense of Style”, cognitive science, psychology professor Harvard – takes science => working principles

Microsoft, Chicago Press as basics, good for new people

How? Details, Examples – Do you add tags, how to/when to

Cascading style guides – in-house SG (minimalist) vs Full SG (comprehensive)

Writing to inform vs writing to convince

Web style != Chicago/Microsoft: Yahoo, writing for web, also IBM.  Good for (1) tech people (2)  newbies to field (3) ESL (4) computer or human translation

Confession: One of our group members reads style guides for fun!

Others write several style guides – knowledge base, differences in users must be considered. Science writing needs it’s own style guide

ESL concerns – using American idioms might not work

Example: The writer dealing with bad docs: audience was the writer; Goal to achieve consistency. Content was procedural, printed, many things didn’t fit (terms, procedures); did own SG to have everything in one place: Start Clean.

People have strong opinions about SG. During Merger, writing teams combined, used Layered SG. Use Publishing SG then Internal SG for exceptions. SG online, searchable. Read me first (Sun), Monthly meetings for new/changed entries.

List out what not to do (British/American)

Reference Dictionary to settle spelling dispute

Product glossary

How much detail? Don’t invent the wheel. Use standard materials. Make it short… Or not? Search mitigates this

When picking base style guide, consider the purpose of the SG (MLA, Words into Type< AP ,MS, Yahoo, Sun)

How to keep track of all the SG you are using? Conscious of who/what you are aiming for; reason to use provides clarity

Realistically, as a writer, how do you get an answer? Co-Workers, Internet, SG, team, physical hard copy, Google.

Working without an editor – have a good reason for exception.

Pick basics, then copy editor makes/notes/records decision

TC in an Agile Environment

Scribe: Cherie Woodward

Top Takeaways:

  • Have a champion for TC
  • Tie docs to dev tasks – can’t close task until doc task is closed
  • entire team learns together

Notes:

Agile – incremental, nimble, development goals, agile manifesto

Work broken into easily complete-able tasks

Shortened time-to-market

Writers fit how?

Get documentation into scrum or sprint

build in reviews

user story isn’t accepted until TC is complete

Daily 5-min meetings: What did you do? What are you working on? (standups)

What problem does story points solve?

Estimate hours = story points. 13 is highest sprint tracking effort

65% time work, 35% time overhead or 70-30 (based on effort, ability, complexity)

Always working on tasks – less downtime

Doesn’t necessarily fit the best model for user assistance

By programmers for programmers

Minimum viable content/minimum viable documentation

Customer feedback?

Jira – link your task to an ENG/Dev task; can’t close task until you close your task. Doc tasks can be skipped until the next sprint

QA – time them into test docs while testing code

Doc tasks created after Dev completes their tasks – get team involved in learning process together

Management buy-in to champion TC