Session 3 Notes – TC Camp 2018

#1 Improving search in technical content / WordPress-SEO

Description:

  • Techniques
  • Tools
  • Who are the users? Internal? External?
  • Personalities, Metadata, Taxonomy, Integrating SEO
  • Let’s continue discussing some of the topics regarding WordPress/SEO from the morning workshop
  • Describe your experience in setting up a WordPress website.
  • If you’ve implemented SEO techniques, were they beneficial?
  • Is WordPress the right platform, or are there better options?

Scribe: Dawn Stevens

Top Takeaways:

  • 2 considerations – Google or onsite – different strategies
    • Google – SEO
      • – title
      • – shortdesc
      • – links
    • Onsite
      • Keywords
      • facets
  • Keyword selection similar to index – need special skills

Notes:

  • Behind firewall, not visible to Google, burden on us
  • Keyword search – how to improve;
  • Faceted search – categorize data; do users use facets
  • Users rather everything and don’t want to overfilter
  • Different mindset from shoppers who do filter
  • SEO – Google ignores keywords – title, shortdesc, metatags, plus other considerations – words appear in body as well, links from other ..
  • On own site – keywords, facets important
  • Penalize word stuffing
  • Companies behind firewalls may be doing themselves a disservice – people come to Google first. Many don’t discriminate where it is coming from.
  • PDF on a firewalled system – have to know where to go, login, find right page, dowload product, search PDF– not an easy process.
  • But fear of competitor.
  • No way to make buying decision if not accessible; doc is a key to purchasing decision
  • Corporate decision about what is facing public
  • Linking strategy is also important (SEO) – quality of who you link to and who links to you…
  • To learn more about SEO – Google publishes guide

#2 Complex doc systems with Markdown and Git / Markdown for techcomm

  • It’s simple to use Markdown and GitHub for a simple set of docs.
    • What if you have a great deal of documentation?
    • What can you expect?
    • Should you even try?
  • Markdown for Techcomm
    • What is Markdown?
    • Is it reasonable to use Markdown for Techcomm?
    • Examples of successful implementations?

Scribe: Bonnie Kim

Top Takeaways:

  • Git
    • Version control mechanism
    • Allows easier collaboration
    • Code-oriented tool
    • Will win points with key audience (developers)
    • Gitmersion.com
  • Markdown
    • Simple language for simple tasks
    • Forces simplification of docs system
    • Limited functionality (bells and whistles) HTML as a fallback language

Notes:

    • What can you expect from using Git?
    • Git is a version control system. GitHub is a content hosting system.
      • Lynda.com
      • Gitmersion.com
      • Static website with Markdown
      • All git commands are from the perspective of the repository, not the user
      • Command line vs GUI (Git Desktop)
        • What are you trying to achieve?
        • Command line powerful
        • GUI easy and visible. Greater control and restrictions on what users can do (and mess up).
    • Developers and teammates happy to help.
    • Five commands: add, status, push, commit, branch
    • Solo or team?
    • Start easy and practice
    • Problems working in GUI → Update issues.
    • Command line sync with developers worth the growing pains.
    • Best practices for working in a team.
      • Well-defined workflow, SOP
      • Have the most updated copy.
      • Git is line-based track changes, not file-based.
      • Dedicated Git administrator.
      • Document everything
      • Reference docs for SOPs
    • Git is shoehorned: Not actually a doc tool but written in the user’s native environment.
    • Between push and commit, there is designated review.
    • Preview before you push. Staging platform.
      • Running local server for seeing graphical representation.
  • Markdown
    • Good for simple docs
    • Complex tables are difficult
    • Resort to HTML hybrid
    • HTML + PDF difficult export
    • Not quite strict enough.
    • Text/doc maintenance is painful
    • Simple, procedural, concepts for devs
    • Very simple procedures

#3  Instructional design for tech writers / eLearning and the role of documentation

Description: 

  • There’s often a lot of overlap between “training” and “documentation”.
  • Are they the same thing?
  • Can one be substituted for the other?
  • Should corporate training and tech pubs documents be merged? If so then who’s in charge?
  • Which is more advantageous from a corporate perspective?
  • For writers seeking to apply for ID positions, what do we need to know first and foremost?
  • As eLearning becomes more mainstream, what role can/does documentation play?
  • What changes are necessary to doc structure, media, and format to make synergy and reuse possible?

Scribe: William

Top Takeaways:

  • Tech Writers as knowledge transfer
  • Linking content through structured
  • Design thinking

Notes:

  • What is ID? IA for learning content.
  • Most cos, background for docs is learning goals.
  • Knowledge transfer → Learning objectives, assessment, certification
  • Tech writers are usually in KT, but learning is downstream. We should connect at LOs.
  • TWs are topic and task-based. Should connect with LOs if LOs are similar to TW topics.
  • What do TWs and trainers have in common? Often they do not communicate.
  • Training is now web-based, LMS, etc.
  • Are writers writing for documentation or instruction?
  • Formal learning taxonomy: Blooms learning taxo – You can remember. Los w/more
  • Formal processes are using the learning taxo to create through to cert.
  • How would an instructor use doc to create instructional material?
    • Learning theory
    • Trend: fewer and fewer graphics in documentation
    • The content is not for the same purpose, but there is stuff that is duplicated.
  • One example: reuse task in docs and learning.
  • Trainers may know more about learning theory, insight into the needs of the learners.
  • Tech writers: Trainers could add links to training materials.
  • Tasks/procedures are written up w/o context. Could supply the same steps written in exercises with context related to different business verticals.
  • Help could have button linked to tutorials.
  • How about testing use cases? Usually no time.
  • Design thinking: Necessarily interacting with end-user.
    • ID needs prototype, testing, feedback.
  • Very little tech writing is involved in social media.
  • Agile: 1 dev cycle, next sprint is when docs catch up.
  • When use cases are being discussed, TC should get in.
  • Product management leads.

#4 Securing remote tech writing work

Description:

  • How can you persuade a prospective client or employer to let you work remotely?
  • Which kinds of teams, organizations, and industries are more (and less) amenable to letting tech writers work offsite?

Scribe: Alisa Bonsignore

Top Takeaways:

  • Opportunities for remote working are limited
  • Companies are struggling to find onsite workers, but they’re not budging (on allowing remote work)
  • Many cost/emotional/environmental benefits to remote work.
  • Sell yourself as a resource, not a cog

Notes:

  • Mixed groups between all offsite and mixed onsite/offsite structure.
  • Major traffic avoidance.
  • Home office limits distractions, pressures of office politics, and fear of office dogs.
  • Clients like to micromanage, have been burned by remote workers in the past.
  • How do companies integrate remote workers & workers in other offices (with onsite employees)?
    • Should be a similar situation for remote & other offices
    • Video conferences, etc.
  • Recruiters try to encourage hiring managers to consider remote workers. Suggest working onsite for x months with possibility of transition to remote.
  • Small companies are more flexible than large. Open source companies are generally more flexible. Not seen with larger companies.
  • Some participants are finding it harder and harder to find remote work opportunities.
  • When the job market is tight, it’s harder for them to find onsite workers and they have to extend to remote workers.
  • And yet onsite is costly for businesses: lighting, HVAC, real estate.
  • Environmentally unfriendly to pump carbon emissions during traffic.
  • Emotionally unfriendly to workers in high-stress commutes.
  • One participant is in-house but works with a remote worker via Skype/Slack just fine.
  • Freelancers have had good experiences with specific project-based work.
  • Another worked ina  virtual business setup with developers based out of the country.
  • It’s hard to fill these jobs, hopefully something will work.
  • Many of us say we actually work more remotely (nights/weekends)
  • You’re selling your problem solving resources, not just another worker.
  • Play hardball.

#5 Tools for documenting REST APIs / Breaking into API documentation

Description: 

  • Attendees who are using tools like Swagger or Postman to help them document HTTP-based APIs can talk about their experiences. Those who are doing ti by hand can hear about the experiences of others
  • The title says REST, but strict adherence to Fielding’s definition of REST is not important for this topic
  • Share experiences about how you got into documenting APIs
    • Your programming experience (if any)
    • The language used, format, tools, etc.
    • Tips for getting into this field

Notes:

This table had no participants, the topic having already been discussed earlier during the day and at the Pre-Camp API workshop. Other topics had higher interest during this slot.


#6 Ways to simplify complexity

Description: 

  • Simplifying complexity is one of the core values tech writers add to a technology organization.
  • But…how exactly do you reduce the complexity of content?
  • What techniques and tools do you employ?
  • From navigation maps to plain language, step-by-step procedures to topic chunking, we employ a variety of techniques.
  • But could we do something more, something truly innovative in order to master this skill?
  • In this discussion group, we’ll examine other ways to approach and simplify complex content.

Scribe: Guy Haas

Top Takeaways:

  • Complicated: many parts and concepts
  • Complex: interactions among parts and concepts
  • We use abstraction
  • We analyze by creating tables, flowcharts, workflow diagrams
  • Trade-offs: complexity can give access to power wherease simplification can foreclose that access

Notes:

  • How to identify user pain points?
  • Go to field engineers – they deal with actual customers
  • Create a grid of options and identify problems
  • Complicated: many parts and concepts
  • Complex: interactions among parts and concepts
  • We use abstraction to simplify
  • Flowcharts & workflow diagrams
  • Complexity can lead to power: mac machine simplifies but makes it hard to go off the beaten path; linux machine leaves things complex but going off the path is in reach
  • Sometimes over-simplifying erodes user confidence (they need to know more about what all it’s doing)
  • Macroview vs microview
  • Consider an 8-step process: on each topic show a high-level view at where we are
  • On-boarding is different from on-going
  • Go for consistency in terminology
  • Adapt tools that enforce consistency of terms
  • How to address the problem of multiple paths?