- Let’s continue discussing some of the topics regarding minimalism from the morning workshop.
- How have you implemented a minimalist approach in your writing?
- Describe some of the benefits you’ve seen from a minimalist approach
- Any down-sides to minimalism?
Scribe: Jay Martin
- Know your user
- Word of the day: Sacrifice – to satisfy the minimal requirements first used in 1651)
- Dawn Stevens said that the . principles of minimal living are similar to minimal writing
- Evaluate your space (what do you need)
- Prioritize what the user can’t live without and choose to focus on personas
- Remove excess
- What about edge cases?
- Don’t ignore core customers. Don’t clutter search results. Let them call tech support
- A place for everything and everything in it’s place
- Make it as visible as possible
- Documentation in the interface means that it isn’t needed in a manual
- Documentation can be complete if it completely helps the user without including steps they already know
- Minimalism includes repetition if users need steps (and haven’t seen other pages)
- Cut topics before translation. In remaining topics, simplify the language.
- Some audiences want friendly but ambiguous sentences. Some (like aircraft inspectors) need clear and longer.
- Download the simplified technical english dictionary for examples.
- Separate old content
- Last point about minimalism: Keep going back, re-evaluating:
- How to use a mouse used to be documented.
- Documentation falls into which quadrant:
- Unique and unknown VS Already Know it
- as measured against:
- No impact of not knowing VS catastrophic not to know
#2 Documentation for the Internet of Things (IoT)
- What is “The Internet of Things” and what sort of docs, internal or customer-facing, might be required?
Scribe: Laurie d’Armien
- Not just data transfer!
- Components: sensor, network, analytics, human evaluation, configuration
- Silly: hairbrush, smart beer can
- Early big brother
- Not just data transfer! Sensors communicate with network
- Installing sensor
- Network setup – sensors to equipment to analytics
- Data analytics – communication
- Human maintenance interaction equipment
- iPhone is a sensor and output
- Different user for different docs
- XML standard for docs
- Standardized nomenclature
- Diverse applications
#3 Getting user feedback
- Are you allowed to talk to your users?
- How do you know what you write is meeting their needs?
- Have you found reliable, affordable solutions for getting constructive input from your audience?
- When you have tour users’ attention, what are your key Dos and DON’Ts for interacting with them?
Scribe: Kevin Hufnagle
- If you can’t talk to your users directly, keep in mind that user liaisons have biased filters
- If users are investing in attending focus groups and conferences, send them a survey
- See if tech support team can find answers to callers’ questions in your docs
- Word your questions carefully in surveys to minimize bias, “other” answers
- Make sure user feedback efforts are vetted by management
- Can you talk to your users? (1-yes; 3-sometimes; 3-no)
- Those who cannot talk directly use customer support as liaisons. (That feedback is filtered! They’re not always focusing on feedback that tech writers would find helpful.)
- Feedback systems are sometimes reliable.
- Some manuals provide feedback form in the back of print manual (don’t have many responses)
- “Game changes” when you transition from print to web, but frequent users annoyed by it
- Best way to provide user satisfaction, according to management
- Systems DO sometimes lead to enhancements, based on user confusion and misunderstanding
- “Was this helpful?” link leads to rsponses while staying out of the way for power users
- Need a full feedback loop (don’t ignore feedback)
- Some users don’t realize that humans need to deal with responses
- Gather proactive feedback?
- Focus groups, talk to product line managers, customer reps
- Can also ask around internally to get a general sense of doc quality, great for validation!
- Product investment exercises in-house can indirectly reveal doc needs, too.
- Docs can also be part of a larger survey sent to many customers (holistic feedback about product). In surveys, word your questions properly to minimize bias “other” answers.
- Take advantage of user investment.
- Traveling to company for focus groups
- Traveling to conferences
- Augment any surveys being done at those events
- Doc search feature includes “request revision”
- Good way to filter inappropriate feedback that you’d receive if you are open source
- User Dos and DON’Ts
- DON’T criticize user’s approach to using a feature
- DO ask users whether their complaints should be escalated to “formal” issues
- DO offer incentives for feedback
- What do we, as user customers, want to see with feedback from companies
- Timely response is helpful
- Allow us to see status of issue
- Even if survey results indicate nothing needs to change, validation is great to get.
- See if tech support team (they are users too!) can find answer in documentation
- If yes, why did user not check docs first? (Is it easy to find?)
- If no, should we add that item to our docs/FAQs?
- Most common tech support call topics == greatest need for documentaiton.
- When talking to users, good end question is: “Was this helpful? Did we meet your needs?” Chatbots should have that question.
- Anything that has a digital footprint has analytics, but need to synthesize data properly to draw meaning from it.
- There’s no standardized tool to create a “was this helpful?” box, but it’s easy enough for dev team to create one for your team.
- If your docs use DITA, ZoomIn (also FluidTopics, easyDITA, SDL Tridon, etc.) web portal collates feedback data and tags feedback on page-by-page basis.
- Marketing dept. Is a good resource for creating and distributing surveys.
#4 Future of DITA / Content reuse mechanisms in DITA
- The DITA OT is an open-source tool. And it’s an important one. It’s used in all of the commercial DITA publishing tools that I’m aware of.
- However, it has a small group of people who develop and support it, as opposed to other open source tools with many people contributing.
- Does this mean it’s a dead-end tool that will shrink and fade with time?
- Is its use expanding or contracting in companies?
Scribe: Dan Littman
- DITA will continue to expand and find more users. Tools will probably catch up to make DITA easier to use.
- Hope support base, tools, and users will continue to be viable
- DITA open toolkit is terrible. It could use Frame, Arbor, Top Leaf
- The whole point is to use it off the shelf. Why would you specialize? The general DITA lets you do ridiculous things.
- Can use a tool that lets you control it so other users do what you want them to do.
- Lightweight DITA: How will it play out? In terms of tools, etc.
- DITA only supports types of information for technical writing, marketing, and training.
- And we can use it with HTML.
- That why DITA was able to expand!
- Most people switching to DITA came from unstructured Frame or Word.
- A lot of unstructured data will be connected to structure, either as XML or DITA. So DITA will expand.
- If investment is made in any of the DITA pieces, you need to have someone involved in implementing and training.
- Other tools like Confluence and Paligo are being used. Modifying DocBook instead of DITA because it’s simpler.
- Will Chatbots migrate to a structured format?
#5 Career paths after tech writing
- Silicon Valley’s demands on tech writers lead many to consider other careers
- Let’s discuss ways we (or tech writers we know) hope to succeed professionally after leaving the doc business
- Some ideas: project management, “Content writing”, UX, Training, proposal writing, product management, patent writing, engineering, website design, investing, sales, marketing, fiction writing, medicine…
Scribe: Andrew Davis
- Climb the value chain
- Find new avenues that companies can monetize
- Sales training – learning skills of persuasion, meeting needs
- Use your natural curiosity to learn and grow
- “Where are they now”?
- Medicine, academic org certifications, investing (list of job titles under desc above)
- Driven by passion or situation? Could be either.
- Software dev cycle is never-ending; refurbish/flip a house – the work stays done.
- Looking for a sustainable role.
- If your hobby becomes your work, does it become toxic?
- Recasting your communication skills
- Are you evolving in your current role?
- People want to grow; tech writers are naturally curious, important to learn.
- Last one standing becomes default expert, some opportunities for growth
- The world is awash with data and not enough people to interpret or communicate it
- Analytics requires higher-level skills. Can you monetize?
- When content/tech writing jobs go, they only hire what they can sell.
- Come out of the shadows, connect with customers. You know you can do better.
- Sales training is an excellent life skill; skills of persuasion, meeting needs
- Valued commodities in many eyes
- Creation of crowd-sourced content
- Curation of crowd-sourced content
- Giving back – nonprofit? How can we apply our comm. skills?
- SBA offers classes in proposal writing.
#6 Writers and product usability
- All writers should be involved in product usability.
- We’re tuned into consistency, identity dovetailing issues, able to create a more usable product.
- We need to speak louder, and more, and make our case better.
Scribe: Gale Naylor
- Engineers can’t always see what’s not explained well.
- Technical writers see inconsistencies and where different areas connect.
- There are many ways technical writers can be useful. Even our managers may not know how much so. We’ve been able to influence changes in a product. We need to insert ourselves earlier into the process. And get ourselves going on deadlines! There’s not an agreed upon definition for usability. But, it’s about getting users to succeed. And there’s a spectrum of usability.
- We suffer first.
- We are the guinea pigs. We have to test the application.
- Getting involved early enough and convincing other we need to make changes when there’s pressure to ship soon.
- Have to force yourself into the process. Just go to the meeting!
- And how your value (for example, bug reports) and become part of the process.
- Sit near and work near dev engineers.
- “Monitoring all the Slack channels is part of my job now.” Because things are moving so fast.
- Documentation-driven development. Start with documenting a feature, how would a user use it (user story) See Readme-driven development article by Tom Preston.
- We are move attuned to consistency. We can show where there are duplicated. It’s expensive to be me.
- We’re in a position to point out when areas dovetail. But, there are issues.
- When consistency is missing in content, users will worry about the product. First impression is the website and docs, which are trusted.
- Agile fails fast, but you only get one chance at a first impression.
- Sometimes it’s lots of little things that add up to a bad experience.
- Feedback on docs is hard to track.
- Docs cover support issues.
- When you have time, usability testing is great.
- Content Usability is Related to Product Usability
- Have to write your way out of a problem is common. You just have to start your high level view while you’re figuring out the high level view. Sometimes you just have to note what to fix next time.
- Docs should be integrated, like software is iterated.
- Introduce designers and devs to good writing and good usability concepts.
- Definition of Usability
- Users succeed at what they want to do.
- Documentation sparks joy. (If not, maybe you need to change it. Trust your gut. Usability is a spectrum where you are always making it better.)
- Do the hard things first.
- Get more information than you need right now.