Technical Communications In An Agile Environment
- Best practices
- “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)
- 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
- Kanban is useful for software in maintenance mode
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
- Using checklists
- Efficient editing best practices
Scribe: Greta Boller
- 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
- 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
a list of things to check in a document
consistency comments to go back and check
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.
- Best Practices
Scribe: Tracey K. Epps
- Technical writers should learn coding and should participate/join with API communities
- 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
- 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
- Take to/observe the users validation and research
- We can break anything
- 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
- Variety of deliverables