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 supplement
  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