Clever Hamster

STC2008 notes: Surviving agile as a floating writer

This STC 2008 session shared the processes and tips used by NetIQ writers, who straddle multiple sprints and products.

Terms:

• Scrum = agile development approach that emphasizes close communication through daily stand-up meetings.
• Scrum master = team member who facilitates scrum meetings, communicates outside the team, and works to solve blocks.
• Iteration = 1-4 week stretch during which a full software development cycle occurs; begins with planning and ends with a demo.
• Backlog = repository for all requirements and wish list items. (tool to manage tasks = Xplanner)
• Capacity = maximum amount of hours a team member can work during one iteration.

No more specs:

• Moving from specs to short "user story" documents
• Allows for easier refinement and rework upon customer feedback
• Helps floating writers avoid bogging down in lengthy specs when they are brought on to the project
• Lean heavily on paper prototyping with screenshots (click-throughs)

Use 3 doc reviews:

1. first draft = technical review of new content specific to that iteration only, before story is closed
2. approval draft = stakeholder review of entire doc set, with sign-off, during hardening iteration; reduces burden on individual writers
3. quality edit draft = internal proofreading before publishing

Scrum requires detailed communication from all team members

• “I’m working on the installer.” -> “I’m working on the new installer screens that contain user credentials for accessing the database. I need help with text on these new screens, so I’ll be coming to talk to Info Dev later today or tomorrow about this.”
• “I’m running test cases.” -> “I’m running test cases for Feature X. I’m about 75% done with those, but can’t get the modify function to work, so I’m blocked on those test cases.”
• “I’m creating the help for Feature X.” -> “I am about done creating the help structure for the wizard Feature X uses. Developer Sally, I’ll need to show you what I did in the mapping file so we can hook up the help to the wizard page code.”

Planning the Release

• Do resource planning per iteration.
• Have a manager or coordinating lead level resources across projects.
• Ensure approval draft comes after Feature Complete.
• Have documentation sections reviewed during active iterations.
• Ensure quality edit draft occurs during a hardening iteration.
• Work on doc-specific tasks and bugs in early iterations.

User Story = software requirement that defines what is to be built, has a priority in the backlog, and relates to others to make up a larger feature/theme

Better user stories: INVEST

1. Independent – Can be worked on without pulling in other stories, can be scheduled in any order
2. Negotiable – Allows flexibility with engineering team, implies it is understandable (easy to pick up)
3. Valuable – Frames stories from customer perspective
4. Estimatable – Allows lead/manager to pull floating writers on to project based on their capacity and estimate of time needed for story
5. Sized appropriately – Lets floating writers focus on smaller pieces and move on and off project more smoothly
6. Testable – Lets floating writers see what the feature is supposed to do upfront and can write more thorough documentation upfront

Better user stories: SMART

1. Specific – Helps in understanding and prevents overlap, which is useful when pulling writers on and off projects from iteration to iteration.
2. Measurable – Helps floating writers know when to mark the task as complete so they can move on to other projects if needed.
3. Achievable – Helps determine if task is realistic.
4. Relevant – Helps determine if task relates to fulfilling the user story, thus contributing to the release.
5. Time-boxed – Helps floating writers know how much work remains and whether the task will be done within the iteration.

When straddling projects, scrum selectively

• Only attend scrums that pertain to your highest priority project.
• Ask the scrum master to email status for the meetings to keep you in the loop.
• Ensure you have a presence on your team so your team doesn’t forget you when you’re not there.

Scoping effort and scheduling

• Revisit previous iteration estimates.
• Block out 20% for vacation, non-iteration work, meetings, planning, etc.
• Do not include the first or last day of the iteration.
• Ensure Development finishes early so testers and writers can finish up before the iteration ends.
• Apply a standard number of hours per user task, based on the level of source material.
• Compare hours required to complete tasks to total hours of team capacity.

STC2008 notes: Writing API documentation

This STC 2008 session by Daniel Wroblewski of SAP Israel introduced writers to API documentation, and he offered this minimalist approach to structuring it:

• Introduction (1 page)
  • Who needs this
  • What can I do with this API (main use cases)
  • How guide is organized
• Quick Tutorial (1-2 pages)
  • “I want to see it working”
  • How to install or reference
• Concepts (2-3 pages, more if needed)
• Reference
  • List of all APIs (e.g., Document! X, Javadocs)
  • Other lists (syntax, types of windows, packages …)

Common goals of API users:

• to get quick overviews
• to get up and running fast, to see it working
• to see all of the cool things the API makes possible

Resources for API writers:

• Discussion groups:
  http://tech.groups.yahoo.com/group/svcstcapi
  http://tech.groups.yahoo.com/group/APIWriters
• Models: Sun Javadocs, Google AJAX APIs, eBAY web services, Microsoft Windows APIs

STC2008 notes: Instructional design for the real world

This STC 2008 session by Jane Bozarth offered alternatives to the methods taught in academic settings and techniques for persuading stakeholders to reconsider their demands and assumptions. Here are my key take-aways:

• Needs analysis on a napkin: assign performance problems to four quadrants, axis "wants to" versus axis "knows how to", low and high:
  • doesn't want to + doesn't know how to = change job position or fire
  • doesn't want to + knows how to = motivation issue
  • wants to + knows how to = remove obstacles (bad process, bad management, etc.)
  • wants to + doesn't know how to = TRAINING will help here, and nowhere else!
• Task analysis on a napkin: to find the critical 20%, draw a set of 4 concentric rings:
  • Outer ring: call it "Everything about the domain"
  • Next ring: call it "What we have time to teach"
  • Next ring: call it "What learners will be able to recall"
  • Inner ring: call it "What learners will be able to use"
  • Mark the inner ring as 20% of all possible content, and ask the SME what few things should go in that inner ring.
• Training course on a napkin: If the user task needn't be done from memory, small job aids may be the cost-effective training solution.
• Objectives for the real world: ensure your objectives are goal-based (create, evaluate, analyze, complete) and not knowledge-based (list, define, describe, compare).
• Seek newbie SMEs: Since most SMEs are "unconsciously competent" (can effortlessly accomplish tasks without being able to explain how), it can pay off to find users who only recently acquired their skills and so are more likely to be able to recall key steps and trouble spots.
• Have trainers evaluate the course! The ROI of testing is proving the validity of the course, not the smarts of the users. Have your trainers complete evaluations of every course they teach, explaining what caused problems, which learners weren't served, weaknesses in the materials and approach, ideas for how to improve it next time. To not collect this information is a terrible waste.

Moving agile processes electronic and virtual

Mike Wethington posted Martin Fowler's article on lessons learned in doing agile with overseas teams. Many of the points struck me as relevant for the problem of telecommuting teams as well:

• Bring distributed developers onsite for critical first iterations of new projects, to get going
• Expect to need more documents than with a collocated team: it's the price of being virtual 
• Extend conference calls with video, especially for project background lectures 
• Extend instant messaging to group-based messaging, such as with Campfire

• Use the shortest sprints possible, even 1 week

• Make acceptance tests the keystone of planning communication

• Do extensive pre-work before iteration planning meetings: send out narratives for each feature (story), turn them into test scripts, answer questions by email, decompose the features into tasks, and get feedback on that breakdown -- all before the meeting

• Leverage wikis (w/ change notification) for everything needed for team reference: story cards, design guidelines, build instructions, notes on progress
• Change the culture to allow autonomy and decision-making to reside in the team
• Ensure that all stakeholders have access to daily builds, to maximize early spotting of problems

For those unfamiliar with how agile teams run their lives without documents, here's how the analog project mechanisms look (courtesy of Melissa, who snapped these photos at her prior job):

Agile Backlog (critical tasks at bottom, less critical above, unclassified at right):

Agile Board (color coded by task type, such as green for user story):

A tool for virtualizing these mechanisms is Mingle, of which I've heard good things.

STC2008 notes: Improving distance education

This STC 2008 session reported findings of an STC-funded study of distance education and a case study for producing online courses from nothing (no materials or experience). The first study (by Rensselaer Polytechnic and New York Life) offered concrete tips for improving distance learning:

• Tag team: Use a course host/MC for every class, to set up, manage chat channels, direct group exercises, and record/archive, offloading the instructor.
• Plan for pain: Expect a third of the problems to be technical (media technology) and another third to be poor use of interactive channels.
• Control eyeballs: Best results come from 100% participation, by preventing/discouraging multi-tasking.
• Be fair: Use round-robin technique to ensure onsite and remote participants are equally involved (fear also heightens attention).
• Use the best: Use media in this order of effectiveness (ease and reliability): conference call (best), video conference, chat, whiteboard.
• Avoid all-in-1: Tools that bundle teleconferencing with video and more prove unreliable; move voice to Skype or similar, and push video to YouTube or similar services.
• Peer power: Seek technology that makes it easy for learners to help each other and interact -- it's effective and they want it.

The case study shows how Credence System jumped into remote learning, to meet customer demands for training when and where they need it. They tackled it with risk-management in the driver's seat:

• Start pro: to get rolling, they hired an e-learning company to create their pilot course and to select a basic LMS for their needs.
• Simple self-study: they focused on spinning off introductory modules to e-learning, so learners could complete those on their own time, as a prerequisite for attending the instructor-led course.
• Simple principles: they followed William Horton's method of finding Test, Absorb, and Do activities for each objective, and they kept all modules to "sit-com" length.
• Simple tools: they used PowerPoint for presentation, Word for demo/simulation scripts, Visio for scenarios, and they had coworkers narrate for them.
• Do pilots: they conducted pilot courses that included content reviewers and representative students, with ample feedback.