technical writers drive ektron’s user-centered development process
DESCRIPTION
Presented at DocTrain East 2007 by Bill Cava and Greg Stout -- On the eve of a production deadline, have you ever reviewed your documentation and caught yourself thinking: “I could have designed this better”? We have, and decided it was time to change. If a feature is hard to document, then it is hard to explain. When something is hard to explain, it is also hard to use. At Ektron, we have a staff of smart, talented, and technically savvy writers with years of experience. And with the classic development process, the keen insights of the Documentation team are entirely excluded until the product is ready for delivery. After many enlightening incidents, we realized there just might be a better way to do things. By turning the traditional development process model on it’s head, and implementing Agile, User Experience Driven Development, we have been able to code faster, code better, provide higher quality documentation, and, at the end, a better user experience. With Ektron’s current development process, significant prototyping and documentation occur for each feature and project before a single line of production code is written. By involving the Documentation, QA, and Support teams at Step One, front-line experience can be added to our development processes. By providing thorough prototypes before development we have been able to reduce costly iterations in our development process. Our process also produces less disposable project documentation The documentation produced through out the process evolves from feature specification to the user explanation shipped in the finished software manuals. Today we will discuss an innovative new approach to developing software that puts the Documentation team at the front of the development process. Since Documentation is naturally focused on the User Experience, by having the Documentation team leading Development, each and every Developer can focus on providing the best User Experience possible. We’ll explain how our new process not only sharpens product quality, but feeds the Developers, QA and Senior management with critical information throughout the process, allowing each group to participate with more completely and efficiently. Learn about how we have restructured our entire development process to a more Agile and efficient machine, focused primarily on the User Experience and producing a more thoughtful and finely crafted piece of software.TRANSCRIPT
Technical Writers Drive Technical Writers Drive Ektron’s User-CenteredEktron’s User-CenteredDevelopment ProcessDevelopment Process
DocTrain EAST 2007
Bill Cava,Bill Cava, ektron Chief Technical Officer ektron Chief Technical Officer
Greg Stout, Greg Stout, ektron User Interface Development Engineerektron User Interface Development Engineer
Documentation Drives our ProcessDocumentation Drives our Process
Documentation plays a pivotal role Documentation plays a pivotal role
in defining all new features and the direction in defining all new features and the direction for all development at Ektron.for all development at Ektron.
Back in the day…Back in the day…
Stakeholder went directly to a lead engineerStakeholder went directly to a lead engineer Engineer developed itEngineer developed it QA tested itQA tested it Documentation documented itDocumentation documented it Support supports itSupport supports it
A Simple ProcessA Simple Process
The RealityThe Reality
Lead Developer goes straight to codeLead Developer goes straight to code solving the “Programmatic Problems” solving the “Programmatic Problems”
Interfaces created to serve code Interfaces created to serve code InconsistencyInconsistency Many cycles of re-developmentMany cycles of re-development Mad Dash through QAMad Dash through QA Delivered LateDelivered Late
What about Documentation??What about Documentation??
The After Dinner MintThe After Dinner Mint
The Hidden CostsThe Hidden Costs
Wasting resources, time, etc, etc,Wasting resources, time, etc, etc, Potentially losing out on qualityPotentially losing out on quality Over time you lack InnovationOver time you lack Innovation Poor interface makes unhappy customersPoor interface makes unhappy customers Poor documentation makes Support callsPoor documentation makes Support calls So many more…So many more…
Who Were the old PlayersWho Were the old Players
To fix the problem, You must understand the players.To fix the problem, You must understand the players.
StakeholderStakeholder DeveloperDeveloper QAQA SupportSupport DocumentationDocumentation
A StakeholderA Stakeholder
A stakeholder directs a project. A stakeholder directs a project. They have a key understanding of theThey have a key understanding of the
projects primary goals. projects primary goals. Their primary job is too Their primary job is too communicate the goalscommunicate the goals
to whomever will develop those ideas.to whomever will develop those ideas. They are involved in reviewing the projectThey are involved in reviewing the project
Challenges of the StakeholderChallenges of the Stakeholder
Analyzing a feature from all angles is difficultAnalyzing a feature from all angles is difficult Communicating is difficult.Communicating is difficult.
What the Customer hadWhat the Customer had
How the Stakeholder How the Stakeholder Understood ItUnderstood It
How the Project ManagerHow the Project Manager Understood It Understood It
How the DeveloperHow the DeveloperBuilt itBuilt it
How we fix it on release dayHow we fix it on release day
What the UserWhat the User really needed really needed
How it was Documented How it was Documented
Is the stakeholder without blame?Is the stakeholder without blame?
Ever meet this Fellow?Ever meet this Fellow?
A StakehorderA Stakehorder
A stakehorder A stakehorder runsruns a project. a project.
They have a key understanding of what the They have a key understanding of what the projects primary goals should be projects primary goals should be BUTBUT they feel that only they can understand the they feel that only they can understand the goals so they don’t involve others. goals so they don’t involve others.
They like to say, They like to say, “ I’ll come back to see if you’ve got it right.” “ I’ll come back to see if you’ve got it right.”
The Stakehorder’s CycleThe Stakehorder’s Cycle
Programmer
Creates Example
Programmer gets a list
of features
StakehorderReviews
the Project
EngineerEngineer
As unchanging as the mountain or the starsAs unchanging as the mountain or the stars The Zen in the process both Yin and YangThe Zen in the process both Yin and Yang The Engineer simply is the engineerThe Engineer simply is the engineer
Engineers fail when they are asked to do Engineers fail when they are asked to do that which is not engineeringthat which is not engineering
QAQA
Job is to find BugsJob is to find Bugs Finding bugs take time and a deep Finding bugs take time and a deep
understanding of the feature being reviewedunderstanding of the feature being reviewed Trained to think about the User Trained to think about the User
QA fails when not given enough timeQA fails when not given enough time
SupportSupport
Talk to Customers everydayTalk to Customers everyday Acutely aware of what confuses, frustrates and Acutely aware of what confuses, frustrates and
angers customersangers customers
See each new feature as a chance to make new See each new feature as a chance to make new friends with people they have never metfriends with people they have never met
DocumentationDocumentation
Job to document each feature so that a new user Job to document each feature so that a new user unfamiliar with the product can use itunfamiliar with the product can use it
Think about everything from User’s Point of ViewThink about everything from User’s Point of View Product wisdom, have been at the company a long timeProduct wisdom, have been at the company a long time Some of the brightest but often the most marginalizedSome of the brightest but often the most marginalized
Documentation fails when not given Documentation fails when not given enough enough timetime or or informationinformation to properly document. to properly document.
Why it DOESN’T WorkWhy it DOESN’T Work
Being a Stakeholder is challengingBeing a Stakeholder is challenging Engineers think about EngineeringEngineers think about Engineering QA takes time and takes QA takes time and takes understandingunderstanding Documentation isn’t given enough time to Documentation isn’t given enough time to
understand the featureunderstand the feature Documentation started at the 11th hourDocumentation started at the 11th hour Documentation out of synch as changes happensDocumentation out of synch as changes happens
How we changedHow we changed
Understanding these roles and what they Understanding these roles and what they COULD bring to the table COULD bring to the table
allowed us to completely redesign allowed us to completely redesign our process to produce even better software.our process to produce even better software.
User Centered Design ProcessUser Centered Design Process
Optimize the user interface around how people work, Optimize the user interface around how people work, rather than forcing people to change how they workrather than forcing people to change how they work
to accommodate the software to accommodate the software
User Centered Design ProcessUser Centered Design Process
Email (dis)organization?Email (dis)organization? Look at the many ways in which people prefer Look at the many ways in which people prefer
to organize emailto organize email
User Centered Design ProcessUser Centered Design Process
Response to Gmail’s approach?Response to Gmail’s approach?
User Centered Design ProcessUser Centered Design Process
Simplifying the structure of tasks, makingSimplifying the structure of tasks, making
things visible, getting the labels right,things visible, getting the labels right,
exploiting the powers of constraint, andexploiting the powers of constraint, and
designing for error.designing for error.
Wikipedia - User_Centered_DesignWikipedia - User_Centered_Design
Usability PrinciplesUsability Principles
1.1. Consistency Consistency • Icons, Titles, Processes, Consistent NavigationIcons, Titles, Processes, Consistent Navigation
2.2. Simplicity Simplicity • Simple tasks should feel simpleSimple tasks should feel simple
3.3. Subtlety Subtlety • Advanced tasks should not interfere with #3Advanced tasks should not interfere with #3
4.4. Discovery Discovery • Software should be forgiving (undo) and helpful (contextual)Software should be forgiving (undo) and helpful (contextual)
How the Roles ChangeHow the Roles Change
StakeholderStakeholder DeveloperDeveloper QAQA DocumentationDocumentation SupportSupport
User (User Experience)User (User Experience)
The Ektron ProcessThe Ektron ProcessPre-Start Development
Front EndTechnical Specification
BackendTechnical Specification
UX Interviews
User ExperienceDefinition
Internal API
Test Plan
ExternalAPI
Internal API
Technical Review
Quality Assurance
Rounds of Review Final
Documentation
UXDocumentation
Training
Quality Assurance
Stake Holder(s)
Customer Service
Platform
Infrastructure
UXDocumentation
Pre-Start Development
Front EndTechnical Specification
BackendTechnical Specification
UX Interviews
User ExperienceDefinition
Internal API
Test Plan
ExternalAPI
Internal API
Technical Review
Quality Assurance
Rounds of Review Final
Documentation
UXDocumentation
Training
Quality Assurance
Stake Holder(s)
Customer Service
Platform
Infrastructure
UXDocumentation
The Ektron ProcessThe Ektron ProcessPre-Start Development
Front EndTechnical Specification
BackendTechnical Specification
UX Interviews
User ExperienceDefinition
Internal API
Test Plan
ExternalAPI
Internal API
Technical Review
Quality Assurance
Rounds of Review Final
Documentation
UXDocumentation
Training
Quality Assurance
Stake Holder(s)
Customer Service
Platform
Infrastructure
UXDocumentation
Now the stake holder meets with a team comprised of people from each department.
They are interviewed by the UX group and specification for the feature are defined
The Ektron ProcessThe Ektron ProcessPre-Start Development
Front EndTechnical Specification
BackendTechnical Specification
UX Interviews
User ExperienceDefinition
Internal API
Test Plan
ExternalAPI
Internal API
Technical Review
Quality Assurance
Rounds of Review Final
Documentation
UXDocumentation
Training
Quality Assurance
Stake Holder(s)
Customer Service
Platform
Infrastructure
UXDocumentation
Documentation starts before coding
Offers direct input into the feature based on experience with the product as a whole
They document the Mockup as if it was the finished product.
The Ektron ProcessThe Ektron ProcessPre-Start Development
Front EndTechnical Specification
BackendTechnical Specification
UX Interviews
User ExperienceDefinition
Internal API
Test Plan
ExternalAPI
Internal API
Technical Review
Quality Assurance
Rounds of Review Final
Documentation
UXDocumentation
Training
Quality Assurance
Stake Holder(s)
Customer Service
Platform
Infrastructure
UXDocumentation
Now Engineers have a complete Mock up showing specifically what the UI needs to look like and how each function needs to work form a user perspective.
When coding they solve problems from the users perspective.
The Ektron ProcessThe Ektron ProcessPre-Start Development
Front EndTechnical Specification
BackendTechnical Specification
UX Interviews
User ExperienceDefinition
Internal API
Test Plan
ExternalAPI
Internal API
Technical Review
Quality Assurance
Rounds of Review Final
Documentation
UXDocumentation
Training
Quality Assurance
Stake Holder(s)
Customer Service
Platform
Infrastructure
UXDocumentation
Offers advice about specific tests they intend to run, before coding has started.
They offer insight about how similar features have failed, before coding is started.
A QA engineer is assigned to the feature to help review and test during the whole production period.
The Ektron ProcessThe Ektron ProcessPre-Start Development
Front EndTechnical Specification
BackendTechnical Specification
UX Interviews
User ExperienceDefinition
Internal API
Test Plan
ExternalAPI
Internal API
Technical Review
Quality Assurance
Rounds of Review Final
Documentation
UXDocumentation
Training
Quality Assurance
Stake Holder(s)
Customer Service
Platform
Infrastructure
UXDocumentation
Pre-Start Development
Front EndTechnical Specification
BackendTechnical Specification
UX Interviews
User ExperienceDefinition
Internal API
Test Plan
ExternalAPI
Internal API
Technical Review
Quality Assurance
Rounds of Review Final
Documentation
UXDocumentation
Training
Quality Assurance
Stake Holder(s)
Customer Service
Platform
Infrastructure
UXDocumentation
““Best-in-class companies are 74 percent more Best-in-class companies are 74 percent more likely than average or laggard companies to start likely than average or laggard companies to start the documentation process at the same time as the documentation process at the same time as the design process.”the design process.”
Best-in-Class Companies Involve TechnicalCommunicators in Early Stages, Report Finds
By: Cecily Farrar, Intercom Assistant Editor Intercom: May 2007
““Involving technical communicators early helps Involving technical communicators early helps the project team meet deadlines—best in- class the project team meet deadlines—best in- class companies meet their documentation targets on companies meet their documentation targets on a 92 percent or better average—and allows for a 92 percent or better average—and allows for coordination and communication in relation to coordination and communication in relation to product changes.”product changes.”
Best-in-Class Companies Involve TechnicalCommunicators in Early Stages, Report Finds
By: Cecily Farrar, Intercom Assistant Editor Intercom: May 2007
What about me?What about me?
What if my group is not a part of engineering? What if my group is not a part of engineering?
Best-in-class performers are 69 percent more likely to place the documentation team in the engineering department.
Best-in-Class Companies Involve TechnicalCommunicators in Early Stages, Report Finds
By: Cecily Farrar, Intercom Assistant Editor Intercom: May 2007
“Increased collaboration between engineers and technical writers keeps documentation up-to-date with design changes and results in successfully hitting launch dates,” …
Best-in-Class Companies Involve TechnicalCommunicators in Early Stages, Report Finds
By: Cecily Farrar, Intercom Assistant Editor Intercom: May 2007
(The best in class (companies) make two-thirds fewer post product launch changes than laggards.)
Thank youThank you
Keep in touch!Keep in touch!
Bill Cava CTOBill Cava CTO [email protected]@ektron.com
Greg Stout UI DevGreg Stout UI Dev [email protected]@ektron.com