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

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.