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

 

 

 

Session Matrix – TC Summer Camp 2016

Session Matrix- Saturday 30 July 2016

This year we had 3 sessions each with 4 different discussions. Every discussion requires a scribe and a facilitator. Scribes keep the notes and facilitators keep the conversation focused and make sure that everyone gets a chance to talk.  Both get special merit badges for their extra efforts!

Notes for each discussion have been posted to the individual session pages.

Workshops- Notes

  1. GitHub Based Documentation Workflows
  2. Content Strategy for Technical Communicators
  3. Work Global- Live Local
  4. Adobe Workshop

Unconference Session #1- Notes

  1. Content Reuse
  2. Writing/Formatting Best Practices
  3. Writing for Hearing/Sight Impaired
  4. Documentation Automation

Unconference Session #2- Notes

  1. Style Guides
  2. Keeping Up With Industry Trends
  3. Documentation Review Process
  4. Content Architecture and Design

Unconference Session #3- Notes

  1. Technical Communications in an Agile Environment
  2. Technical Editing Fundamentals
  3. Documenting APIs
  4. Writers and Product Usability

Unconference Session #2 Notes – TC Summer Camp 2016

Style Guides

Description:

  • More than just look and feel
  • What goes in a typical style guide?
  • How to look at your docs to create one.
  • Who should own it?

Scribe: Rachael Lussos

Top Takeaways: 

  • A style guide is a value system
  • Revise style guides as necessary and at least every five years

Notes: 

  • Merge individual office style guides with the institutional style guide (eg. GPO), which serves as a back-up-GPO is based on the Chicago Manual
    in education(community college)we have no style guide but we use a handbook and MLA documentation
  • A style guide is a value system
  • Viqui uses Microsoft style guide for nouns; we have seven definitions for “option”
    use cheat sheets to help transitions between different style guides
  • Also develop checklists of the differences
  • Consistently use one style guide and then develop a system for switching to another style guide
  • Use a subliminal mnemonic when transitioning between style guides, such as changing the desktop background per guide or document first
  • Accessibility is part of the style guide;e.g. font size, no merged cells
  • Use Goggle analytics to determine how users are using your stuff (eg. viewing videos), and use that to inform your style guide
  • In teaching, make sure your students know how to access and learn style guides, rather than teach a specific one
  • Markup- applying catergorization is part of your style guide

Keeping Up With Industry Trends

Description: 

  • Techniques to keep us with current industry trends
  • How do you keep your skills up?
  • What resources keep you current?

Scribe: Doug Egman

Top Takeaways: 

  • Read idratherbewriting.com
  • Go to conferences/camps!
  • Network
  • Self-education (eg.lynda.com)

Notes: 

  • Take advantage of conferences, reading (STC pubs)
  • Look for training and professional development opportunities
  • TC blogs (eg-graphics)
  • Network, especially with consultants who work with multiple clients
  • Digression- how to write short documentation, intergrate graphics
  • Industry now expects broader expertise in design and programming whereas in the park writing was the focus
  • Audiences have changed from lay audiences to technical audiences (documenting
  • APIs and SDKR); mine B2B
  • Reoccuring theme:tech writers need to be able to learn technical and programming tools and systems (often on the fly/on the job)
  • Self-training:lynda.com
  • Tech writers must be willing to learn new technologies; adjust and change
  • Role of mentoring- helping new tech writers-improve writeing skills
  • Core skills and ability to learn
  • Website: I’d rather be writing.com- tutorials, writersua.com

Documentation Review Process

Top Takeaways: 

  • Rochester of STC is using slack for CTPC course.

Notes: 

  • Having a designated editor is better than peer review
  • Tracking hard copies of documents helps
  • Read it backwards for copy editings
  • Authoring tools have evolved but not the review process
  • Better ways to review
  • Adobe PDF review can be used for review and changes/comments-can be brought into Robohelp
  • Technical review and Editorial Review
  • Symmantec-first started with editorial team and then moved to peer review
  • How do you both reviews in a short span-when you are working in agile environment
  • What happens when the process breaks
  • Someone comes and gives the feedback in the last minute
  • Breaking down the review process into stages
  • Early draft, medile draft, final draft.
  • Co-ordinating time lines is important in this scenario
  • Setting expectations at each stage is important
  • Discuss your schedule in advance with other team members
  • Issues in using sharepoint for review process
  • Developers don’t think it’s their jobs to review documents
  • Not a good idea to allow developers to dictate the documents
  • Using slack for review process. You can start specific channel for a document review.

Content Architecture and Design

Description: 

  • Organize and plan authoring in a distributed model

Scribe: Jenny Stacey

Top Takeaways: 

  • Content Strategy- content management usla distributed model. How much is too much? mapping.
  • Flauk Strategy- best practice- analytics- support- tickets

Notes: 

  • Organize and Plan
  • What does it mean? Challenges? Solutions?
  • Content from scratch- productions in progress-things to goggle
    discussion: tc users?
  • Managed cloud cenurion, what write users want, deceedo pims process, reg’s defriend? help to find direction user needs scope. feels rigs featuring regular-
    releases seems pissman (audience roles);mapping processing, talking to users to find/processes similarities, digression. End user references are important; want to talk-how much is too much?
  • Project documentation make if accessible for high usage researchable, what do they need-