#1 Improving search in technical content / WordPress-SEO
- 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
- 2 considerations – Google or onsite – different strategies
- Google – SEO
- – title
- – shortdesc
- – links
- Google – SEO
- Keyword selection similar to index – need special skills
- 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
- Version control mechanism
- Allows easier collaboration
- Code-oriented tool
- Will win points with key audience (developers)
- Simple language for simple tasks
- Forces simplification of docs system
- Limited functionality (bells and whistles) HTML as a fallback language
- What can you expect from using Git?
- Git is a version control system. GitHub is a content hosting system.
- 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.
- 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
- 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?
- Tech Writers as knowledge transfer
- Linking content through structured
- Design thinking
- 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
- 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
- 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
- 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
- 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
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
- 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
- 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
- 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?