Unconference Session #2 Notes – TC Camp 2016

Documenting APIs

Description:

  • Documenting APIs

Scribe: Todd Lewandowski

Top Takeaways:

  • API Docs are “hot”
  • Necessary to have a programming background, however small. As much as you can!
  • Lots of free resumes online & through library to learn coding
  • Deep guide for all functions (references)
  • How To Guide for tutorials, Getting Started (concepts)

Notes:

  • API Docs is “hot”. Good for job future. Easier to transition if came from programming background. People have large codebases, now they’re ready to make them work together.
  • What is the tipping point where and API doc is necessary?
  • wait until problems appear
  • when communication really REALLY breaks down
  • esp training[?] for new lives[?]
  • show value now for future growth
  • Tom Johnson (free course)
  • JavaScript & Python – two best to start
  • Programming skills are super helpful (at any level & any language). Though your particular project varies.
  • Codecademy, Santa Clara/SF/San Mateo library card access then access to online repositories.
  • What are good or bad examples of API doc?
  • Swagger (tool) for REST APIs, or RAML – to make specifications in a good format.
  • Deep side w/ parameters, variables, etc. (references)
  • How To Guide w/ tutorials (concepts), Getting Started, examples
  • SOAP APIs

Jobs

Description:

  • Job searches.
  • How to break into a new industry.
  • Hot markets: looking outside the techdoc box.
  • Portfolios – how to construct them, best practices, strategies for wowing recruiters.

Scribe: Tonie Flores

Notes:

  • Ping Pong – Hiring mgr fears you’re a flight risk.
  • They know recovery is slow, state all the things you’ve learned, put manager recommendations on LinkedIn.
  • Against non-existent no one wants to do our work. It’s hard.
  • Kids don’t know what it is. People hate to write.
  • (Dot bomb 80% loss of jobs.) for recession, tattoo on our back, Rather than let jr. developer go, Sr. tech writer goes.
  • Google – must work onsite.
  • “I can learn that” ends interview.
  • Talk geek with them. Otherwise, scares them
  • “You need to know more about their technology than they do about what you do.” — andrew
  • Call their bluff – “this is how I served that problem.” or “You called me for an interview, I
    must have some of what you want, here’s what I can do for you in 30 days, 30 days, 90 days.” don’t just apologize and cave.
  • Scratch a frontier, eg. open source.
  • Sells doc & training. Software is free.
  • Trend toward contract is hire. They are finite and infinitely renewable. Try & buy model.
  • Compensation 1099 – 45-50, Salary 95-100 med devices
  • Developer < 65 staff 120-135 geekiest of geeks.
  • Company cost 22% employer costs to client.
  • W2 can pay benefits pre-tax – vacation, medical, 401K
  • Get paid faster, can file for unemployment, 1099 – Large companies won’t, small companies do. Audit bait.
  • Monster: pitfalls – vendor mgmt systems, field glass
  • Vendor owns you for 6 months, company wide any job

How to integrate “sustainability” thinking into your work

Description:

  • Learning to ask questions about how sustainable a product or technology is, in parallel ways that we have learned to ask how usable a product or technology is, is an upcoming “need to know” skill.
  • Applying technical communication skills for sustainable purposes – where is there a need?
  • Many companies now have “green teams,” “sustainability initiatives,” and “corporate social responsibility (CSR)” departments. Some companies focus on developing products that help people and companies be more sustainable in one or more ways. All of these need people with technical communication skills, although they may not think of it as needing a “technical writer.”

Scribe: Adam P. Hunt

Top Takeaways

  • What can you do?
  • What does it mean for people?
  • Solutions. How does sustainability become normal?
  • Research “triple bottom line” business practices.
  • Ask product managers about product lifespan.
  • Make sustainability normal.
  • Ways to get involved. 360.org, Nerds for Nature, Cradle to Cradle certification
  • Just ask.

Notes:

  • Linda Urban, speaker.
  • Making sustainability relevant to the tech and tech writer community.
  • How to make a more sustainable workspace, product, and planet by both business decisions and personal choices.
  • Sustainability as product differentiation, energy consumption, and recycling efforts at the workspace.

Teaching traditional writers to write topic-based

Description

  • What is the most efficient way to teach a traditional writer how to write topic-based content?

Scribe: Liane Takahashi

Top Takeaways:

  • Provide overview, introduce paradigm, high-level why’s
  • Define topic types
  • Provide samples, examples; demonstrate improved usability
  • Define information types

Notes:

  • Define “Topic-based”, “Traditional”
  • Format vs. Content
  • Typewriter -> DTP -> content-only
  • Academic view of writing (persuasion, reference)
  • Customer-based: customer needs to know now
  • Topic-based is bare necessities immediate application Every page is page 1: search engine point of entry
  • Concepts, reference, tasks can be integrated in different ways
  • Trad. docs can still be built from topics
  • Trad. method: One author owns a book
  • Topic-based: parts of books are owned
  • Complicated procedures cannot be broken into separate topics although same sub procedures could be reused in other procedures
  • Only topic-level without transitions is choppy
  • Reference guide writing is good model for topics
  • Chunk tasks: long docs are harder to read through
  • Book: “Every page is page one” by Mark Baker
  • What is it wiki based?
  • Scope
  • Practical apps
  • Use cases
  • Value
  • How big is a topic
  • Readability, no “walls of text”
  • Depends on user and what you want to achieve
  • Non-tech writers tend towards narrative, arguments

Style Guides

Description:

  • Style guides – more than just look and feel.
  • Style guides – what goes in it and how to look at your docs to create one.

Scribe: Cheryl Hunt

Top Takeaways:

  • Style guides can encompass much:
    • Entire doc structure
    • Formatting
    • Visual elements
    • Typography
    • Wording
    • Dictionary
  • Many style guides available online including Microsoft, Apple, IBM, Yahoo
  • Some apps that can enforce word style are Acrolinx & Hemmingway
  • FrameMaker can enforce visual styles
  • Some that enforce structure are templates, XML
  • Best method of custom – style author, small committee w/ moderator and iterations

Notes:

  • Consistent look, feel & voice very important to look professional.
  • Talk to SalesForce to find out more on styles for video
  • Include examples in style guide of when the pattern should be used.

Elevate content initiatives across the enterprise

Description:

How to elevate content initiatives across the enterprise

Discuss best practices to elevate content initiatives across an enterprise and the various tools and strategies that illustrate the value of content initiatives; align to broader corporate-wide strategic initiatives; identify and track key stakeholders and their spheres of influence; and how to go about enrolling people.

Scribe: Greg Urban

Top Takeaways:

  • Need to get buy-in with stakeholders
  • Need to have consistency with usage of content with other users of the content.
  • Follow the money – content usage needs to increase and support sales. Can garner support for your content initiatives.
  • Persuasive sentence – “My job is to showcase your work” (get buyin) Get your peers to be ware of the problem. Have a bunch of people agree that a certain issue is a problem.
  • Use buzzwords – “User experience” and point out you need users

Notes:

  • Creating social media forum posts
  • Small articles / forum posts
  • Align with marketing – align with needs for deliverables from other departments.
  • Consistency – working – usability testing