Why are release notes important? Presentation given at STC Rochester chapter's Spectrum conference in April 2016 (at Rochester Institute of Technology).
2. WHAT ARE WE TALKING ABOUT?
• What is a release?
• What is release documentation?
• How is it like CliffsNotes®?
• Why is it useful?
• Why should I care?
• Tips and things to consider
• Questions?
3. Who am I?
• Tech Comm Manager
(Black Knight Financial Services)
• STC Associate Fellow
• STC Community Leader
• STC Summit Chair
• Presenter & Speaker
• My story… Todd DeLuca
@TechCommTodd
4. WHAT IS A ‘RELEASE’?
@STC_Rochester @TechCommTodd #spectrum16
5. It’s Something
New or Revised
• Hardware or Software
• System or Platform
• Book, journal,
magazine
• Policy or Legal
Decision
• Device or Gadget
• App
7. It’s a Summary or
List of Changes
• Overview
• Highlights
• Synopsis
• Key Elements
8. HOW IS IT LIKE CLIFFSNOTES®?
@STC_Rochester @TechCommTodd #spectrum16
9. They capture the
’essence’ of what’s
released
• Condenses Content
• Tells Major Story
• Highlights Main Points
• Covers Plot Elements
• Paints the Big Picture
• Shows Samples
13. WHY IS IT USEFUL?
@STC_Rochester @TechCommTodd #spectrum16
14. They Serve a Need
and Variety of
Audiences
• Where Most People Start
• Great for Busy People
• Leaves First Impression
• Different Uses
• Different Content Types
• Used by Multiple Groups
15. WHY SHOULD I CARE?
@STC_Rochester @TechCommTodd #spectrum16
16. They Are an
Opportunity
• Relatively Easy to Produce
• Cost Effective
• Already Have the Skills
• Simple to Assemble
• Something Else to Deliver
• Provides Value
17. Other Benefits
• Bigger Audience
• Connect with Others
• Future Looking
• Future Proof
• Regular Deliverable
19. TIPS & THINGS TO CONSIDER
@STC_Rochester @TechCommTodd #spectrum16
20. Process
Considerations
• Understand Limitations
• Plan for the Time
• Know the Schedule
• Solicit Contributions
• Get Review (QA)
• Determine Delivery Vehicle
• Publish & Promote
• Gather Feedback
21. Production
Tips
• Start Slow & Expand Later
• Keep it Simple
• Make it Consistent
• Produce Regularly
• Leverage Current Content
• Use Existing Tools
• Link to other Resources
• Consider Images
22. Content Tips
• Be Specific
• Use Appropriate Tone
• Avoid Vague Entries
• Bug Fixes
• Performance
Enhancements
• For Issues (Bugs)
• Include Scenario
• Consider Testing
Might be something that is ‘rolled out’ or delivered
Examples:
Software or Hardware (most common)
System or platform (SaaS, website or intranet)
Device or product (consumer item, medical, pharma, …)
Paper or journal article
Book or magazine
Policy or legal decision
Proposal
Summary or list of changes.
Not full story
May or may not be detailed (level varies)
It’s often the ‘short’ version of a longer piece (or set of pieces).
Summary or list of changes.
Examples:
Release Notes
Summary
Overview
Why are they useful?
Starting point for most people
Helps them navigate and get a sense of ‘place’
Busy people like them
Less time to read
Easy to digest and understand
Great to pass along (easy to share and explain)
Leaves the first impression (encourage deeper dive)
Variety of users and uses (more or more)
Inform, educate, train
Used by Multiple Groups
internal and external
Serve different audiences
Product teams
Sales & Marketing
Quality Assurance & Testing
Product Support
Training
Clients
Used for different purposes
Why should I care?
They’re relatively easy to produce
You already have the skills
Most content is already available
You’re likely already familiar with the material
Cost effective
Don’t need new tools or processes
Utilize existing staff
Don’t take a lot of extra time
Something else to ‘deliver’
add to your ‘bag’ of tricks
Shows initiative and your value
you can ‘filter’ content and pick the important parts
Provides value
Your company is delivering ‘more’ to their clients or customers
Saves company time and money (fewer questions, easier on support, …)
What are some other benefits?
Bigger audience
More people will view or read
Better exposure for you or team
Connect with Others
Establish ties with other groups or departments
Future Looking
Increasingly replacing traditional deliverables
Last time you saw or read a manual
Most release changes are posted online (accessed by mobile devices)
Future Proof
New tech needs it
Regular deliverable
Updated regularly
Steady ‘work’
Help yourself and increase your value
Add to your toolkit
Increases your value
More skill and experience
Offer as a ‘service’
Increase value at work
Help Others Share
Get their updates viewed
You act as deliverer (include in your deliverable)
Be recognized as a supporter (and get partial credit)
Process Items
Understand the limitations (focus)
It is what it is (lipstick on a pig)
You won’t please everyone (it’s never enough)
Do you have time?
Will others help?
Expect to deliver consistently (every time)
Do what you can support (sign up for what you can deliver)
Deliver via best vehicle
What audience prefers (spreadsheet, PDF, email, …)
Consider multiple options (for mobile, web, …)
Get others to contribute and participate (give them a stake in it)
Work with other teams and departments
Publish and promote
get into many hands
Assist with delivery
Gather feedback and improve
Production Tips
Keep it simple (start with basics first)
Get practice and gain traction
Add more as you go (start slow)
Keep consistent
Style and format
easier to view, read, digest
Use standards (format and formula)
Leverage current content (material you already have)
Use existing tools (nothing fancy)
Link to other resources
Don’t try to do to much
See also for more details
Add pictures (thousand words)
Use highlights and call outs
Content Tips
Be specific
Cut to the chase (no extraneous info)
Use appropriate tone
Know your audience
Is is a game, app, or medical device
Don’t be too creative
Avoid value entries
Bug fixes (like what?)
Performance enhancement (what does that mean?)
Does it crash less, is it faster?
For bugs, include scenario
Under what circumstances did ‘bug’ occur?
Think about testing
Can your customer validate that the ‘issue’ no longer occurs?
Is there enough info or context to test it?
Which points did you find most useful or compelling?
Could others find this topic area useful or valuable?
Can principles translate more broadly?
Does it outline a problem or opportunity?
Could this topic be developed into something more substantial?
Is there a better name or label (not ‘release documentation’)?
Would this make an interesting workshop or tutorial?
How? What would you look for?
More examples
More ‘how to’