Notes from all sessions were shared at the end of the day in the final Summary Session. Notes from those scribes who sent them in have been posted here.
How to build your help structure and navigation for web help – product based vs process based, etc
Facilitated by Neal Kaplan
- Several writers in the room were involved in moving from heavily UI-based docs to process or task-focused docs.
- Users want to know, “How do I do my job?”
- How do you associate topics to a dialog box if you are doing context-sensitive Help? (When you have multiple tasks for a single dialog box.)
- Need to approach documentation from both sides – some users need to know how to do a task, and some users need to know what a widget does.
- Minimalist writing – how do you decide how much content you need? How do you know when there isn’t enough content? There was a lot of discussion of how to use metrics to track which content customers actually use. Some were using Google Analytics, others proprietary tracking systems.
- An unusual take on the value of topic-based writing – the complexity of a topic can be used as a metric for the complexity/difficulty of the task. This can be used to improve the user experience.
- Using collapsible sections to hide extended discussion can be a nice way to balance the needs of users who want quick info versus those who want more detail.
- Search vs. ToC versus index: Are customers still using ToCs and indexes? Anecdotally, writers have noticed that some users and reviewers don’t seem to see ToC’s when they’re there.
- Many users don’t read in detail. Put your important info up front. Give a meaningful set of link choices.
- One of the side-effects of a cloud-based world: We don’t have the same de-facto standards that we did when people were tied to an operating system. (For example, Windows UI conventions and Microsoft Help provided a consistency that people were used to.) Now every interface looks different, and every help system looks different.
- Some people just like PDFs. Is ePub a viable alternative?
- The distinction between Help and PDF/manual is not so strong any more.
- What is the impact of writing for translation? How do people handle graphics for translation? Most people limit screenshots because of translation cost, but users like them. They have visual appeal, provide a “You are here” signpost for the user
TC in an Agile environment
Facilitator: Shari Clare (Voltage)
Scribe: Amy Bowman (VMware)
- Overview and general thoughts
- Shari started by describing some of the Agile process and commonly used terms
- The process provides continuous feedback to the team members about what is going well and what needs to be changed
- Agile increases the visibility of the documentation/the information developer if you are a part of the process.
- You see SMEs on a daily basis.
- Everyone is equally responsible for the story being accepted. If no one has reviewed the doc and the story can’t be accepted, the whole team is “at fault”, so the team is theoretically more likely to help you when you ask (for example, to review docs).
- Scrum won’t solve your problems. If your dev team has problems, scrum will put the issues in the spotlight rather than fixing them. Don’t blame scrum if you still have issues after adopting it.
- Training is key! Teams must have solid foundation in the principles of the process to be successful
- Different teams might have different levels of maturity (experience with Agile). This can introduce conflict when teams try to work together.
- Suggestion from session participant: Scrum in a day. Have the group do a day-long exercise/off-site where they learn the process by going through a scrum-in-a-day.
- Suggestion from facilitator: Training by Mike Cohn of Mountain Goat Software (can be done online)
- Suggestion from session participant: Should tech comm be the people writing the user stories?
- Agile doesn’t really take docs into account. We are forced to retrofit the process to get our work done.
- Sometimes UI components aren’t done until the very end
- Possible solution: docs lag behind the development by one iteration
- Possible solution: decouple the doc tasks/process from the dev process. Have separate scrums with your writing team and then sync up with dev every week
- Collaborating with offshore teams
- Possible solution: weekly sync up (scrum of scrums — meeting of the scrum masters). Provides forum for requests, get to know each other
- Possible solution: Send each other a list of stories and tasks you have worked on every week
- Possible solution: Put watches on stories to see when they change
- Possible solution: Record your daily stand up via WebEx. The offshore team views your stand up before they do their stand up (and vice versa – you view theirs before you have your stand up).
- Suggestion: Go to visit the team or have them visit you! If possible, this is a huge step toward successful collaboration
- Doc work doesn’t always fit with/align with development work. (For example, a ten-line code change might be a one-hour task for a developer, but it might introduce eight hours (or more) of work for the docs.)
- Possible solution: If a user manual (for example) doesn’t match up with the dev work, it can have its own story. Break it down into chunks that you can demonstrate at the end of a sprint.
- Where do you fit in tasks like release notes, indexing, general maintenance?
- Possible solution: Some people said that these tasks can be done when the dev work for a user story doesn’t have doc impact.
- Suggestion: Acceptance criteria for a story should include the doc tasks — the story isn’t done until the docs have been written, reviewed, review feedback incorporated, and doc “demo”ed.
Wrangling difficult personalities
- Find common ground, become their best friend
- India people like to be asked about their families
- Ways to work with remembering names
- If you don’t remember name, show that you remember something about them
- Difficult bosses
- have witnesses – get evidence, save emails
- see employment attorney (not HR)
- make emails specific “x told me to do/not to do this”
- don’t brown-nose
- When you get work requests that are verbal: send email summary of conversations, “CC” those who may be affected (i.e., projects are “at risk” or affect timelines)
- Book recommendations – Snakes in Suits, The Psychopath Next Door
- Dealing with screamers: find the one person who can shut them down
- Unavailable SME: send email, copy boss, people ducking you..
Basic competencies for entry-level and advanced information developer positions-> and implications for training/education, from certifications to degree programs, to advisory boards, to general professional development; skills for new writers, portfolios
How do you decide what content should go into a doc for the mobile version of an enterprise software app? Do you rewrite or just cut down on amount of content?