- Inspiration and guidelines for injecting humor into tech docs
- Your favorite technical communicator joke
Scribe: Tom Magliery
- Humor is conditional in many ways
- Different things work in different media.
- Different things work for different audiences.
- (Ironically) Using humor is contrary to the idea of removing distraction.
- Salesforce won an award for humor in tech docs for Trailhead.
- The danger of humor is that it’s cultural.
- What’s funny in one context isn’t in another.
- Lawyers and politicians are fair game.
- What can be done in tech docs?
- Lighter tone as appropriate.
- Use puns and wordplay to catch the user’s eye.
- Writers can be more liberal in internal communications.
- Epigrams could be useful.
- Metrics showed humor made readers more receptive, and they read more.
- Use juxtaposition, surprise, hyperbole, irony, puns.
- More about SFDC (?) — funny things tend to be re-tweeted
- Content for mobile devices.
Scribe: Laurie d’Armien
- Consider user’s environment.
- Consider space for content: length and width per device.
- Use responsive app design and ensure content fits on all devices
- Reference Ann Rockley for mobile content
- Examples: DITA, epub, iPad
- Style guide is essential
- Reference Pronto forums for examples of responsive help
Taming the MS Word Monster When Moving to XML
- Top gotchas when moving from Word to XML.
Scribe: Ben Colborn
Essential is some kind of consistent taxonomy structure
- Tech pubs and education solutions/collaboration
- Difficulty in setting standards across organizations.
- Reduce overlap by converting legacy documents to structured
- Separate authoring from publishing
- Everyone says the want XML for reuse, but they really want control over Word.
- Can have any number of info types as long as authors understand them.
TC in an Agile Environment
- While an Agile environment spurs a wide variety of experiences, writers must ensure that docs are complete every sprint, and that reviews are built in to the plan.
Scribe: Elizabeth Semmelmeyer
- Wide variety of experiences.
- Need to include docs as part of the process.
- Agile often gets blamed, but it’s really implementation.
- Agile is designed for small teams.
- Significant lack of design docs.
- Big picture isn’t detailed; best to start with a small piece.
- Doc tasks must be visible, and included in sprints.
- Reviews should cross multiple scrum teams.
- Constant refactoring.
- The time to bring up issues is in the retrospectives. Track issues at each scrum team meeting.
- Writers are on multiple teams. Writers shouldn’t be on multiple scrum teams.
- Scrum master creates stories and facilitates meetings. Should assign owners to reviews.
- Dev has other priorities.
- Many meetings aren’t relevant to documentation.
- Content spread across scrums; multiple doc tasks.
- Complete doc tasks every sprint.
- Ensure team gets scrum training.
Promote Yourself via Social Media
- Using social media for self promotion and job searches.
Scribe: Talya Flowers
- Join different groups related to your field.
- Connect with like minded individuals in your field.
- Step outside your comfort zone
- If you have 500+ followers, you are an influencer.
- Participate by liking, following various blogs, sharing relevant articles, and making a presence in your communities to expand horizons and jobs will come to you!
- Facebook, Twitter, and LinkedIn used by majority in group
- Twitter is nebulous because of the 140 character restriction.
- Use relevant hashtags. Post articles of interest to show that you’re relevant and knowledgeable.
- Use HootSuite to post to multiple social media sites at once, tracks hits and likes even geographically.
- Use LinkedIn to promote your business. It’s visible to prospective employers.
- Business vs. Personal:
- Be cautious about the content you post
- Personal and business should not mix
- Twitter is the best option for self promotion; potential employers can see how active you are and how much you think about it.
- Use best judgement and be polite.
- Retweets, @ mentions, and hashtags affect number of hits
- Write reviews
- Best time to tweet is during commute hours
- Use polls
- Hoot Suite
- Periscope to do mobile broadcasts from cell phones
- Skype for podcasts; accepts multiple participants
Keeping up with Industry Trends
- How to keep your skills honed.
Scribe: Jessi Lawrence
- Have a desire and make the effort
- Network. Participate in communities, blogs, etc.
- Create a community.
- Reach out: at conferences engage with vendors, speakers, peers
- Research competitor’s docs
- “Current” is already behind. How do we anticipate?
- What do we do? Conferences, networking, etc.
- Keep abreast of new books and articles
- What are other people doing?
- What do other groups use for tools?
- Explore terminology on the web
- Use consultants. They need to keep on top of what’s happening in the field.
- Always look for things to learn
- Attend Write the Docs meetups
- Techwrl blogs
- LinkedIn groups
- Read the requirements for job postings.
- Ask others to explain new trends and teach others.
- Git is collaborative and has sandboxes to try new things (all in markdown)