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.

Workshop Notes- TC Summer Camp 2016

GitHub Based Documentation Workflows

Scribe: Hilary Fraley

Top Takeaways: 

  • GitHub is a web-based repository for software projects.
  • GitHub uses Git, a distributed version control system for software development.
  • Approxiamately 1/3 of developeres use GIT for code management.
  • The branch structure is logical, alllows you to treat docs like code and takes you out of silos.
  • All projects collaborators can review and contribute.
  • There are a few options for working in GitHub.
  • Options for working in GitHub:command line,GitHub web site, GitHub desktop app.
  • The general GitHub workflow is create a branch, add commits, open a pull request, discuss and review, and merge and deploy.
  • Documentation options include READMEs, Wikis, and GitHub pages, GitHub adds features like issue tracking and feature requests.

Notes: 

  • Free individual and company accounts;create public repositories, contribute to projects.
  • Paid account is required to create private repositories.
  • Companies concise buy GitHub Enterprise for internal use.
  • Opportunities for Technical Communicators on GitHub; contribute content, edit content, add comments on public repos; Create project docs and manage communities on private repos;track issues, manage project files, create project docs on GitHub Enterprise.
  • Terminology: Repositories(“repos”) are the most basic GitHub element. They’re like project folders;they contain all files for a project.
  • Branches are parallel versions of repos.
  • Branches don’t affect the master branch, so they are a sage way to experiment forks are personal copies of author user’s repo that live on your own account.
  • Collaborators have read/write access.
  • Commits are revisions. Pull requests are proposed changes.
  • Merging means taking changes from one branch and applying them to another.
  • Issue control contributors can note issues with project files.
  • You can create labels and milestones and discussions for different issues.
  • Version control: GitHub offers a unique concept of master branches, other branches, and making local copies.
  • Integration: There are approximately 90 productivity tools you can integrate with GitHub.
  • GitHub Golden Rule: Anything in the master branch is always deployable.

Content Strategy for Technical Communicators

Scribe: Jeanette LeBlanc

Top Takeaways: 

  • Bottom line is biggest driving factor, prove ROI
  • Intelligent content the goal but “minimum viable,” is the bare minimum: available;accurate;appropriate(connected intelligent)
  • Bad delivery can conceal great content
  • Three phases: assessment, recommendations, implementation plan and estimates-suggest a small pilot project

Notes: 

  • C.S within ID/actors org.-getting hard to draw a line between
  • LearningDita.com-free course ware, can contribute courses
  • What is CS? Use info products to achieve the org. goals
  • Business obj: $$, distinguish from competition, referable
    ISBN; legal- Cheap content PDF only; low value, unclear, out of date, etc.
  • Critical success factors:
    -change management
    -risk management-pilot helps
    -tech risk management(performance)
    -storage management
    -culture
    -strong team(skills assess)
    Beyond technical communication:
    -Connect across silos, show business case, with numbers,convey version so people -understand the benefits, think like a customer (very effective), collaboration: can help customer(very effective)
    -Collaboration: can help customer experiences
    -Road blocks: accountability, culture, resistance to change, time/priorities
    -Bridge the gap:educate, meet, show value
  • Expanding goals: as you achieve each piece, you can scale up

Work Global-Live Local

Scribe: Kate Bowerman

Top Takeaways: 

  • Use of video chats can help enhance communication
  • Thorough meeting prep-take the time to do equipment checks and meeting prep
  • Foster a remote-friendly can have and build relationships with collegues
  • Stay focused at home-set up a distraction free environment;build in breaks and obc time.
     Notes:
  • How people wound up working remotely
  • What is Salesforce and our roles at Salesforce
  • Stay visible and engaged- moving up; stay visible; communication tips.
  • Video use- cultural-“office hours”- can increase
  • Perception of visibility-thinking, expressing appreciation
  • Formal reports that highlight work-newsletters
  • Meeting prep-consider upgrading equipment every few years.
  • USB mix are good quality with mute button
  • Send gifts to thank people-incentives-snack box
  • Exchange-send a chat-be flexible to meet team-timezone needs
  • Team culture how to foster good productive culture
  • Question of the week/ice breakers
  • Virtual happy hours
  • Virtual coffee chats
  • Lunch locally-professional groups-host when people travel to your area.
  • Wine and dine
  • Cross segment and collaboration
  • Anger from coworkers who can’t work from home
  • Have boundaries work/non-work time
  • Staying focused when working remotely
  • Set aside office space just for you
  • Groom for success
  • Move it-Don’t just sit there
  • Standing desk
  • Wireless desk
  • Time out plugin- plan your breaks
  • Work clothes first thing in the morning
  • Evgo suite
  • Have a social life
  • Shut down work on office hours

Adobe Workshop

Scribe: Madeline Graham

Top Takeaways: 

  • Up to 40% of tech writers spend their time formatting-Frame Maker frees up time for content by automatically applying template
  • Authoring and publishing tool in one
  • Allows you to import multiple docs and automatically apply preset
  • Allows interactive, linked 3D models in PDFs

Notes: 

  • Importing Word-publishing capability-no programming knowledge necessary,
  • Graphical interface allows you to pick and choose criteria
  • Structured frame Maker=the whole thing.
  • Only way to get this choice is through pop-up a installment or through edit and preferences.
  • Use structured, no benefit to choosing unstructured.
  • Can send .fm documents for review by converting, review will importt as trach changes
  • Authoring=”work space drop down,”a set of different tools based on job e.g.
  • Design, Authoring. Also allows you to reset your workspace after moving things around.
  • Also allows different wstom workspaces for different users.
  • Imports docs as links rather than image; smaller file size. LA choice to “Copy in doc” or “import as reference”
  • You can make preset file and choose that when importing multiple docs that you want in the same format.
  • A style with at green dot= no FU style exists
  • Tips for new users: choice for standard or structured templates when starting document
  • Can tag info thats repeated as a variable: automatically takes IP format when inserted (no need for format painer or ctrl + F replace)
  • “Update book” option updates index, table of contents, pages etc-great if you move chapters around
  • Three pages that make up template:
  • Body-Master-Reference(index)
  • U3D-file ext. for 3D models
  • Can publish to mobile app for mobile accessibility, Ebooks, Adobe digital pub solution, HTML resonsive-can change publishing settings depending on medium e.g. brown headings for web vs. blue for PDF
  • HTML5 allows you to easily design interactive documents-search, toggle, glossary, etc.

Unconference Session #3 Notes – TC Camp 2016

Documentation workflows based on Markdown and GIT

Scribe: Matt Ness

Top Takeaways: 

  • GIT and Markdown go together; GIT uses text files and opens in Markdown by default
  • Writing documents in GIT enables you to use the same content workflow as your engineers
  • Markup does not enable the same amount of formatting capability as other authoring tools, though you can augment it with HTML
  • Good editors- Notepad++, SublimeText, Atom, MarkdownPad

Notes: 

  • Kamodo- have good markdown support
  • Markdown is a markup language- how is it implemented. One of a family of text based languages- intended to be easy to use. The markdown site gives you a WSYSIB view of your output.
  • Scribe has contract job where he was asked to use XMGTAL, but this is not good for his project, Markdown advantage; used to let developers into GIT. Not as flexible as Word or Framemaker w/r/t styles and formatting. Markdown is like simple HTML.
  • Markdown may be too simple say some.
  • Discussion of formatting-you can do a lot with its basic markup and then add HTML for advanced formatting.
  • Pandec is a good markdown- HTML converter is very scrib similar with markup.
  • You do not need to add HTML/CSS to it, would look like HTML 3.
  • Sequence is CSS does not apply until markdown is converted to HTML.
  • Chrome extension to view markdown
  • Markdownpad- view/edit markdown files
  • How do you generate markdown structure
  • GIT- using for documentation- Use to monitor changes to documentation and track changes
  • Discussion of GIT workshops- all internal communication are managed through GIT
  • These are organizational issues, not technical issues. GIT respositories use Markdown by default.
  • When you do your pull requests- same as source code- the doc reviews.

Localization

Description: 

  • Writing for it, publishing it, managing localized content, process engineering, best practices

Scribe: Alan House

Top Takeaways: 

  • Preparing your conduct- Acronyms is ideal, other “checking” mechanisms exist
  • Localization- local acceptance is important- GIGO
  • Human workflows are still best
  • Make sure you own the TM
  • Machine translation is you have training data

Notes: 

  • How to prepare your context for localization?
  • Some LSPs will localize screen shots

Metadata and Categorization strategies for technical writers

Scribe: Shari Clare

Top Takeaways: 

  • Mindmapping can help define content structure
  • Once you have the correct structure, content can be moved to be correct document type
  • Metadata is useful for: metrics, governance (where content can be used), finding information faster, getting more information of what something is, “Is-ness”- the difference of what something is

Notes: 

  • Google is a mindmapping tool, which helps you figure out the structure so you can put content into the right document
  • Reuse of content is one of the goals
  • Standards can be used as categories to help identify parts of data, which can be put together or to a whole document
  • Mental structure analogy is like Amazon, which lists topics, then drills down into a variety of categorie
  • Taxonomy falls under the field of information architecture
  • Smartlogic is a tool for managing tazonomies

Introduction to Data Modeling: How to Start Thinking About Reuse

Scribe: Guy K. Haas

Top Takeaways: 

  • Understand the problem- what elements are constant in repetition, and what are variable
  • In your tool, determine what functionality(variable,conditional, snippet or text inset) to use
  • Data modeling has a long ramp- up time when it comes to re-use. Rules for naming, categorizing, etc. But it pays off at translation time

Notes: 

  • Governance processes might be necessary depending of scope of project. If someone else might take it ever, or if multiple authors are involved– need to document the logic of the reuse
  • Some tools are better than others at supporting governance
  • Need management of governance
  • Establish the atomocity of reuse
  • If a topic has more than 20% of its content as reused material, split it.

Leveraging LinkedIn

Description: 

  • Leveraging LinkedIn to get yourself noticed. Since Andrew spoke last January, they’ve totally transformed the UI and many of the features, so even someone who attented last year will get value from the presentation.

Scribe: Peter Jew

Notes: 

  • Any power wars? Moderate. Try to update regularly so they won’t forget.
    Too much update- recruiter gets triggered and get calls
  • In mind is one advantage, but it has become very hovey.
  • Sometimes you get someone who already connected with
  • Get recommendations and references
  • Get consistent references- you can edit and work with the recommendations
  • Best way to get a recommendation is to ask the person to recommend yo and tell them what you wanted to be.
  • You should also rejuvenate
  • Goggle search- add “tech writer”
  • Most recruiter will go to LinkedIn first before they post a job
  • You can restate the skills last at the bottom
  • If a recruiter contracts you, respond even if you don’t need a job.
  • Other people may mind your network and connections- you can set visibility on connections
  • Add photo
  • Keep your resume more detail and specific to the job- LinkedIn should be genuine and lots of keywords
  • Join LinkedIn groups and keep abreast of head
  • When browsing for jobs- stay obscure if desired
  • Premium gets directed email and advanced search
  • Job seekers may get premium and get to the top of the list
  • You can contract recruiters via twitter

Writing/Formatting Best Practices

Description: 

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

Scribe: Karl L. Leader: Bonnie

Top Takeaways: 

  • Depends on context, audience, etc. “Never any absolutes.”
  • Semantic markup lets device and style sheets determine look and format, using some tag and each case.
  • Best practice for typography may not be same as tech writing
  • Automate formatting
  • All differences have to be “neat”, be consistent as much as possible. Not arbitrary inconsistency- (yet maybe appropriate with informal tone)

Notes:

  • Proposal: 2 levels of headers, level 3 gets blurry.
  • Scemantic tagging= fonts/formats imply meaning. Made with code “what it is” not represents, emphasithes. Categories
  • If topics maybe heirararcal or equal depending on context.
  • Use a minimal number of headers, no more than necessary
  • Conceptualize device format “large vs small” not “mobile vs desktop”
  • Have a style guide and use it! Different devices have new action verbs. Eg. “cick” vs. “tap”. Write specific to device or more generic terms like “select”.
  • Research= Trend m mobile.(Apple uses no numbers)
  • Steps in procedure do not have to be numbered.
  • Priority is to fit content on smaller screens rather than numbered list. But very technical does benefit from if steps.
  • Strong based tutorial,no numbers.
  • Move to casual tone of voice- moving to allow contractions- even in LBM style guide R MS style guide
  • (Advertising seldom was complete sentences)
  • People jump to images, sleep text blocks
  • (A lot of tech writing rules are based on research)
  • IEEE professional communicators publishes academic journal.
  • How many have done usability testing of content.