Unconference Session #3 Notes – TC Summer Camp 2016

Technical Communications In An Agile Environment

Description: 

  • Pros/cons
  • Tips
  • Best practices
  • Successes
  • Failures

Top Takeaways: 

  • “Definition of done” varies by shop
  • “Agile fall” fairly common methodology
  • User stories useful and come from different groups (product management,Business Analysts, Information developers.)
  • Gives information developers a louder voice (standups)

Notes: 

  • Different ways to do it. Frustrating and wonderful. Often one sprint behind.
  • “Agile fall” process common.
  • Pros: iterative(We like that)
    easier to tweak product
    gives team members permission to speak up
    culture improvement
  • Kanban is useful for software in maintenance mode
  • Cons:
    hard to define
    frustrating because you can’t finish
  • What is agile scrum?- scrum is an agile methodology-scrum leader runs meeting and helps set priorities
  • User stories can come from different groups- product management, doc, business analysts
  • “Definition of Done”
  • When does doc set done? I sprint back?
    two back? at end? with dec?
  • Varies with shop. If you aren’t releasing to public at the end of sprint, no harm done being I sprint behine. Use your expertise to advocate for Info.Dev.

Technical Editing Fundamentals

Description: 

  • Using checklists
  • Efficient editing best practices

Scribe: Greta Boller

Top Takeaways: 

  • Good technical editors transfer knowledge
  • Relationships become shorthand between authors and editors
  • The worst thing you can do is send a reader back
  • Editing is best when you “other” your text

Notes: 

  • Technical editing means differnt things to different people
  • Lone writers are responsible for editing their own content
  • What is technical editing?
    -cleaning a document to what level? how much time? rewritting?
    -anything that doesn’t involve generating new content
  • Checklists?
    a list of things to check in a document
    consistency comments to go back and check
    acronyms, terms
    comments to self when editing in doc
  • Track changes: can people see revision history? comments? plays into the writing and editing process. Use templates for comments
  • Can be overused
    okay when there’s a relationship between authors
  • Can we actually change technical words?
  • SMEs not best writers (shifting terms, passive voice, ambiguous pronouns)
    need to change a bit, but can be dangerous
    ambiguity, who picks?
  • provide edit in comments is an option
  • Style Guides:
    document existing style and suppliment
    iron out ambiguities
    helps new hires
  • Tips: edit backwards paragraph by paragraph, read aloud or have Adobe read aloud, print and physically edit-othering your text
  • 1. clarity 2.economy 3.readability- how to edit after content is good.

Documenting APIs

Description: 

  • Tools
  • Workflows
  • Best Practices
  • Training

Scribe: Tracey K. Epps

Top Takeaways: 

  • Technical writers should learn coding and should participate/join with API communities

Notes: 

  • APIs provide coding info for others to use to develop other apps.
  • Interface is like any other interface(command line)-APIs need documenting
  • Learn coding (implementation/language)-so that you fix errors
  • Start with C++, Python….if you want to be successful at writing APIs.
  • API developers and designers value tech writers
  • Python is a huge API community
  • URL is a tool helpful for writing APIs
  • REST APIs= a contract that has code (w/details(implementation) that new users can use to client apps.
  • Most firms use “design font” methos- allows for all players, stakeholders to comment/have influence on design, then the develops build (the details)
  • Representational state transfer=REST
  • To be successful: Read Oauth 2.0- Specification
  • Read Google and others to research “Gold Standard”
  • Go to API meetups
  • All tech writers should read/learn this standard for client development
  • For sample APIs docs.oracle.com

Writers and Product Usability

Description: 

  • Writers should be involved in product usability
  • Hardware as well as software, APIs as well as GUIs
  • We’re the canary in the cool mine(we suffer first)
  • When it’s hard to explain, it’s hard to use–docs won’t help
  • We’re more tuned to consistency than most
  • Creating examples, exposes gaps in the functionality matrix
  • We can identify “dovetailing issues”
  • When we can help to create a more usable produce
  • We need to speak up and learn how to make our case better

Scribe: Viqui Dill

Top Takeaway: 

  • Take to/observe the users validation and research
  • We can break anything

Notes: 

  • Helen is our facilitator.
  • How many of use are involved in product UX- content- wireframe- info vs call to action- no connection with users- menu- consistency- someone has to care about the content at the beginning
  • Analytics- what’s used the most?- searches- user journeys- user goals vs client goals
  • Planning and Strategy- clients think they know- technical writers can bridge the gap- requirements-bad requirements-bad design-dogfooding-many voices informing the design
  • UX terms- who is going to use-design phase
  • We Can Break Anything- end to end- real world- people enter stuff wrong- error messages- skip afield
  • Training- defining terms-what is it?before how we use it
  • Typos are forever in index field
    -some fields not editable-unchangeable fields that change-ill considered database decisions
  • End users
    -writers vs developers
    -clients vs vendors
    -talk to real live end users
    -user research
    -personas
    -surveys
    -analytics
  • Variety of deliverables
    -written
    -graphics
    – video
    -examples
    -illustrations