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

 

 

 

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-

 

Unconference Session #1 Notes – TC Summer Camp 2016

Content Reuse

Description: 

  • How to find reuse
  • Planning/tracking reuse across your documentation set
  • How to author for re-use
  • Authoring to different formats- reauthor, just reuse, audience analysis, pluses and minuses
  • Keeping a handle on your reuse, reuse strategies, thinking like an information architect

Scribe: Tracy Epps

Top Takeaways:

  • Content reuse means different things(in different industries)
  • Content reuse can help reconcile concepts and terminology
  • Implementing content reuse starts with planning and processes
  • Content management systems are ideal, though
  • Metadata can be important content reuse

Notes:

  • Could mean repurposing content; modular content
  • Content reuse- different content for organizations/ companies
  • Can chunk content to a grandular level and create snippets
    snippet of content- reused in multiple planes(embedding reusable content)- similar to single source?
  • repurposing content(not necessarily copy/paste)
  • Content life-cycle- content needing discussed should be repurposed/reused
  • Problems to solve with content reuse
  • migrating documents/multiple repositories
  • Reconciling concepts and terminology
  • To implement content reuse:
  • create a management plan for content reuse
  • spot check for duplicate topics/work with team to help (across products)
  • Create a doc catalog
  • Software shows/flags if content is in other deliverables/doc catalogs.
  • Not just a tech problem…It could be a planning or tracking problem
  • How to Track Content/Audience
    -one solution/example=sharepoint checklist-tracks entries-ex:((subject and release
  • info/identifiers))
    -assign writers to write new topics
  • Use dita and metadata to–attach to documents to help with later reuse and content management systems (cms)
  • Create a content reuse system- use tools that you have socialize it amoung team/associates
  • Important for knowledge transfer
  • Authoring for reuse?((How to))
  • When possible, write generically (esp. for white-branding)
  • Watch gender, number, etc.
  • Use shared objects
  • Create/adhere to naming conventions (for docs and graphics)
  • Put process in place, and enforce the standards/processes
  • Authoring To Reuse?
  • -Write an SOP
  • Information Architecture- what is it?
  • -Analyzing content and structuring documents
  • -Building a blueprint for documentation and content
  • -Outlining ideas/concept (for how users will use content)

Writing/Formatting Best Practices

Description: 

  •  Standards as they apply to the technical writing profession, process, and data items.

Scribe: Marilyn Woelk

Top Takeaways: 

  • Word features that help with style
  • Reviewing bulleted lists
  • Which goals to incorporate into a documents when client vs. user goals are different
  • Ways to estimate document lengths

Notes: 

  • Using styles in Word is a time saver. Using the Style toolbar can help you clean up styles from multiple authors who often copy formatting from other documents.
  • You can overwrite style customizations by individual authors.
  • Word has feature called styles. H has ~ 20 defaults.
  • You can create a template and define styles. Then when authors create in that template the styles will be the same.
  • Auto correct- in bulleted lists.
  • Uncheck Capitalize first word of sentence, or it will cap bullets.
  • AP style guide is good.
  • Complete sentence with colon works well
  • Use a number- The following five steps
  • Implied rank or order- Alphabetize lists.
  • Complete sentence, begins with cap, ends with a period.
  • Using lowercase bulleted items with commas at the end is now archaic.
  • Lists: bullets vs. numbers, etc. Also list in text vs. bulleted or numbered lists..
  • Instructions are problematic as one big block of text.
  • Only use numbered lists if items occur as a sequence.
  • Numbered lists can also be helpful in long lists so you can refer to a specific item you reference.
  • Marketing- generally uses bullets
  • Sometimes adding number (the following five things) limits editing.
  • If you are putting items in text and have more than 4-5 items listed, they should probably be bullet-ed.
  • NIH research shows that people on screen scan left to right for a few lines and then scan down left column and dip into text where they are interested.
  • Column and dip into text where they are interested.
  • This may indicate the need for bullets, on more screen vs. print.
  • When do you push back on customer when writing.
  • End user documentation
  • Look at plain English guideline
  • Part of our expertise is in communicating to specific user audiences, we need to identify audiences, do focus groups and assesment and determine what isn’t working(re hot like calls).
  • Then develop something.
  • Audience- identify this when looking at document maintenance, avoid “above” and “below” use
  • Modular layout: Helps with revising sections of a manual without reordering the whole manual
  • New TC professionals need to understand collaborative drafting. Learn how to write to your audience and what the end goal of the communication is supposed to be.
  • Cleint or management goals vs. user goals.-
  • Analysis,Composition, Editing
  • Time management/ bounding by time(hours) or by pages/words/ 250 words- make point to intelligent audience
    400 words to make point to unintelligent audience
  • You can gauge total number of words vs. how many points I need to make.
  • To estimate a project, do an outline and estimate number of pages or hours for each subject
  • Maintaining lists- sometimes you need to view time to update vs. value of new content

Writing for the Hearing/Sight Impaired

Description: 

  • Braille and Audio
  • Content conversion
  • Authoring considerations
  • Redesign issues
  • Thinking about content differently
  • Section 508 compliance

Scribe: Helen Sydawar

Top Takeaways: 

  • Make sure the content is concise and well written
  • US-section 508 International-WCAG
  • Add alternative info or tags in source files-
  • avoid manual rework in Adobe Acrobat
  • Proof read all alt text
  • You tube auto captions need to be proofread and rewritten

Notes: 

  • Section 508 compliance
  • Language usage- “select” vs “Click”
  • Fragment headings with important information up front
  • Use about section
  • Use Acrobat “Read Aloud” feature (available in Acrobat
  • Reader also) to see how text flows are rendered.
  • Using alt-text-make sure that it gets proofread
  • Standards- section 508 (US gov’t) WCAG (international)
  • Use Youtube capturing for roles as a starting point, but it needs to be proofed.
  • Daisy format for e-pubs
  • Acrobat has no “undo” for typing
  • Add the tag and alt information as early is possible (in source
  • Word or Powerpoint) and avoid post-processing in Acrobat when possible

Documentation Automation

Description: 

  • Challenges
  • Issues
  • Planning and adjusting
  • Tools to automate publishing in multiple formats

Scribe: Danielle Villegas

Notes:

  • Architecture of the document itself – arch of content (how do they relate to each other) but also design of the page (formatting, how it looks); There’s the underlying model of the content, then how it’s applied with the design (topic, then topics arranged in maps, then visual design, etc.)
  • Anything you do over and over is something that needs a macro or assembling files over and over–that necessitates automation, whether it’s a tool or scripting. Many ways to automate the process. In web environments, it’d be CSS.
  • One of the difficulties is that we have multiple outputs for single documentation, and that can be messy, but certain products can help with that.
  • Unstructured content is more difficult to automate, but it can be done, depending on the tool. As long as you are consistent with how you format in unstructured, that can help a bit. Cleaning up top level tagging and such and minimizing renegade tagging to make things consistent can make a big difference.
  • There doesn’t seem to be a way to automate the reviewing process the same way that we can automate the production process.
  • Structured authoring environment helps with this process. XML is generally the standard for structured content, but some use MS Word, data from databases or CMSs or other formats.
  • Content reuse provides better consistency for structured writing, which then lends itself to easier automation.
  • One of the difficulties with tagging and document design is that different outputs will yield different visuals. There are tools that can accommodate those variances, but not all do.
  • Accessibility issues add another layer of complexity to the process, but applying those needs through automation as well.
  • Sometimes understanding personas and how people are using the information can help with structuring the documentation.