Workshop Notes – TC Camp 2016

Content Strategy

Scribe: Amy Bowman

Top Takeaways

  • Traditional tech writing (concept, task, reference) is not dead-just delivered differently.
  • Make content engaging, entertaining, and experience.
  • Type and Content-discover, learn, do
  • Make writers content strategists-give them the vision let them decide how to meet it-what’s best for your own content?
  • Notes

Salesforce-“Doc is dead”

People introducing themselves and what their challenges are in the area of content strategy. Four of people seem to be moving from traditional doc to more modern doc at the request of their management. Content teams are misaligned and could be misrepresenting the brand. Docs should focus on “when to and why to” not just how to. Content experience-reflects on the brand. Interactive and gamified content-gold star effect. Strat w/UI text. Help only for things you can’t explain easily in UI or walkthrough. Complement with video, ?????????? Progressive discovery-iceberg-provide content in progressively more detailed chunks.

Git

Presenters: Jamie, Jen, Stefan, Training.github.com

Scribe: Bonnie Kim

Top Takeaways

  1. Create Branch.
  2. Add commits.
  3. Open Pull Requests.
  4. Discuss and review.
  5. Merge and Deploy.
  • Git hub can be customized for your workflow!
  • Gihub is useful for version control and record keeping.
  • Work off of local copy and branch. NEVER off of master.
  • You can work off of website, desktop client, or command line.

Notes

Working primarily off of github.com-friendly user interface. Traditional workflow is tech writing workflow.

“Understanding github flow”

  1. Create repository.
  2. Create branch.
  3. Add commits.
  4. Open Pull Requests.
  5. Discuss and review code changes.
  6. Deploy! (squirrel)

Github tech writing workflow

2 repositories:

  1. Doc strategies.
  2. Help docs repository → issues

Tickets → push to docs. Very descriptive branch names. Atom text editor. Commit often (pull request ASAP). 1 commit per change (200 per round) local changes → web PR pull request “close issue #s” w/key words Mega branches → accumulates changes across multiple smaller branches organizational tool (best practice branch management NEVER WORK OFF MASTER – ALWAYS WORK OFF BRANCH → DEPLOYED STATE → PUBLISHED

Git is designed to make branching EASY!

Pull request; push request → requiring higher-level approval G tech writers (including managers) for 400. Make changes and push changes LOCALLY. Then deploy or be very descriptive of hat changes you made per commit. Liquid Syntax → markup language by shopify → used in Jekyll (for high end use).

Non-pretext software version control gets tricky Access for developers and new writers-advantage of plan text file. Even if GITHUB goes down… Everyone has local branches command line access is encouraged, but web- and cs-clients are available for easier user-access.

Feature or document branches-per separate unit before you start work → do GIT pull Fetch → step before pull to recap change history → compare local repository w/master (TRUST) Pandoc → converter HTML → Markdown (3rd party) w/manual checks Pure markdown for simplification

Recommend creating ReadMe populated with IMPORTANT INFO for users, contributors, etc. – project info of notes issues → Bug; suggested fix → labels, milestones, assignees → ready for review, SSH (topic), etc

Collaboration requires extending and granular communication mention users teams, etc.; keeps records of everything start now!

Park, and open pull request.

Keeping Yourself Marketable

Scribe: Karen Aidi

Top Takeaways

  • Roles for technical writers are unequal.
  • Most valued to least valued roles:
    • Most valued: Developer Doc
    • Less valued: End-user, system admin doc
    • Least valued: internal procedures or compliance documentation
  • Sectors for technical writers are unequal.
  • Hot: mobile, big data analytics, saas/virtualization cloud, security, open source
  • Lukewarm: enterprise, medical devices

Notes

  • This is a huge topic and Andrew could not cover it all in two and a half hours. If you want to find out more information for example, on how to present yourself on your resume, see Andrew’s website: www.synergistech.com.

What is the market like? It’s:

  • Cost containment is job#1.
  • Hybrid roles are prevalent.
  • No training available. Carrot and stick leadership. Greed, fear, and layoffs.

Locations are unequal:

  • Hot: San Francisco
  • Cold: Santa Cruz
  • Lukewarm: South Bay

Finding Opportunities

  • Networking is still the best way to get a job. Getting a referral matters. For off the radar opportunities, go to:
  • LINK SV: www.linksv.com (discover off the radar listings)
  • LINK UP: www.linkup.com (current, under-publicized listings)

Training

  • Be prepared for your job interview.
  • Understand the technical domain by exploring online training:
  • Code year
  • com
  • com
  • com

Interviews

  • Go to Andrew’s website for interview tips.
  • Arrive rested, well-informed, and armed with lots of questions.

Negotiations

  • Determine how much you need to live on.
  • If you contract, check out ???????.com

UI/UX Writing

Scribe: Joanne Grey

Top Takeaways

  • Think end-to-end: new user/first we-ongoing-deeper understanding
  • Early integration is key.
  • Measure success/problems with good metrics
  • Consistency instills customer confidence and trust.
  • Patterns create consistence. Develop a pattern library.
  • Patterns let customers think less.
  • Voice conveys who we are and our relationships with the hearer.
  • Tone conveys the situation and emotion (lead the way, keep it simple, be upbeat).
  • Make sure tone is appropriate.
  • Voice and tone adds value, metrics can confirm.

Notes

  • Long metrics matter: reality check, areas for improvement, plan resource use and manage up.
  • Keep team excited, settle disagreements.
  • Use feedback during process is important.
  • Consistency across UI/UX provides clarity, instills user confidence and trust.
  • Share your style guide across the team. Guidelines for mobile, global, abbreviations.
  • These guides can become the basis for patterns.
  • Patterns provide a common language across the team.
  • Attendee observation: There is no such thing as “intuitive” only “familiar”.
  • Patterns and styles are always evolving. They let the team learn from each other’s work. Patterns help globalization.
  • Voice is consistent but tone can change. Voice says who we are and define our relationship. It’s your personality. Tone is relevant to the current situation.
  • Read content out loud. Watch for positive/negative feedback, collect and document examples. Add voice and tone guidelines to style guide.
  • What do you want to get out of this? Mobile use, globalization, orienting, learn more, UX designer not equal to UX writer., web content interest, how to talk to eng, methodologies.
  • Adding value through consistency and patterns.
  • Voice and tone (and emotions in between).