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.