COMMONSENSICAL TECHNICAL DOCUMENTATION - IIBA ...

COMMONSENSICALTECHNICAL DOCUMENTATION

CommonSensical Technical Documentation

Learning ObjectivesW

IIFM

–What’s

InIt

ForM

e??

Learning ObjectivesAcceptance Criteria

● Why Technical Documentation & Communication Are Vital To Any Project

● How To Turn Complicated Ideas Into Simple, Lean & Agile Communication

● How To Avoid Common Pitfalls & Mistakes


Bad Documentation = Disastrous ResultsNo One Reads It

If it is too long, boring or contains useless information

No One Understands It

If it is complex or has jargon or technical terms

Reader Makes Assumptions

If it is unclear, vague, or incomplete

Reader HasWrong Info

If it is not reviewed, inaccurate, or not kept up-to-date


What is the CommonSensical Approach?

Know The Basics

Get TheJob Done

Stay Out Of Your Own Way


Disruptive Thinking Challenge


? ?


CommonSensical Thinking!

Disruptive Thinking Leads To


IMAGINEImagine & Reflect: Smile Project

Imagine You are asked to document the following: 1. Provide instructions for someone to smile2. Explain the reasons why they should smile


User Story Number: 100 Priority: 7Story Narrative/Title: Size: 5How and Why To Smile

As a human being,I want to move the muscles in my face into a happy gesture,So That I can make myself and others feel better

Story Type: Customer Exploration Factor/State: Active

Acceptance Criteria

Success● The orbicularis oculi which encircles the eye socket,

squeezes the outside corners into the shape of a crow’s foot.

● The zygomatic major, which resides in the cheek, tugs the lips upward

Failure● The orbicularis oculi which encircles the eye socket, does

not move● The zygomatic major, which resides in the cheek, does

not tug the lips upward


Please Make It Stop!!!


IMAGINEImagine & Reflect: Smile Project

Imagine You are asked to document the following: 1. Provide instructions for someone to smile2. Explain the reasons why they should smile


SMILEIt makes you feel better.

It makes others feel better.


Too Little Just Right Too

Much

GOLDILOCKS Dilemma


Case Study 1: More technical writers and business analysts than developers

● Long and difficult to understand● Too much time in reviews and updating of

documentation● Just as complicated as if not more than the

functionality it was communicating● Rarely used after the product launch

GOLDILOCKS Dilemma

Too Much


Case Study 2: Client did not want to invest in documentation ,because it, “wasn’t worth it”

● More time & resources spent in meetings● Decisions and changes caused confusion● Continuous back and forth emails/messages● When functionality failed to meet

expectations, there was nothing to reference

GOLDILOCKS Dilemma

Too Little


Know The Basics: History | Timeline


Early documentation begins around the time of the invention of writing.

The first technical writers were inventors who wanted to share their theory and findings.

Modern technical writers create documentation for almost everything.

Early Documentation 1st Technical Writers Recent & Modern


Early Cro-Magnon Man Cave Drawings


Paul Otlet is considered to be the father and founder of technical documentation

First Technical Documentation


Know The Basics: Bodies of Knowledge


For Project Managers

For Business Analysts

For Technical Writers

PMBOK Guide BABOK Guide TCBOKProject ManagementBody of Knowledge

Business AnalystsBody of Knowledge

Technical CommunicationBody of Knowledge

Know the Basics: Bodies of Knowledge


9

10

Underlying Competencies

Techniques

9.6.1 Office Productivity Tools and Technology

Anything with the words Modelling, diagrams, maps, as well as user stories or use cases: 10.7 • 10.11 • 10.12 • 10.13 • 10.15 • 10.17 10.23 • 10.32 • 10.35 • 10.36 • 10.4110.42 • 10.43 • 10.44 • 10.47 • 10.48

What to Focus On from the BABOK Guide


1 Introduction

Throughout the Guide

1.2.6 Project Management Business Documents

The outputs section of each phase or technique

What to Focus On from the PMBOK Guide


What to Focus On from the TCBOK


CommonSense would tell us, one of the first questions you need to ask yourself before you begin writing is:

“Who needs to know this information?”


Stakeholders & Executives

Developers & Analysts

Users & Subject Matter Experts (SMEs)

Project Support

Audience Types


Is It Possible To Have More Than One Audience?


Match Your Language Match Your Audience


What is it? What will it be used for?


● Product Documentation Artifacts created to describe product-related information

● Project DocumentationDetail and instructional artifacts generated during a project life-cycle

Two Similar But Very Different Meanings


Project Documentation

Product Documentation


When will it be needed? When should it be started?


STILL WAITING!!


Projects Never Start In A Kick Off Meeting


Technical Communication Should Not BeginAfter The Kick Off Meeting


Why is technical documentation still important?


FDDS

CRUM

DSDM

RAD

XP

C Y T L

A

• Feature Driven Development• Extreme Programming• Adaptive Software Development• SCRUM• DSDM• Rapid Application Development• Crystal

What Do These Have In Common?


All were created before the year 2000 to solve the biggest challenges faced by software development

• Lack of Communication• Not Delivering On Time• Failing to Succeed

FDDS

CRUM

DSDM

RAD

XP

C Y T L

A

What Do These Have In Common?


AGILE MANIFESTO

On February 11-13, 2001, at The Lodge at Snowbird ski resort in the Wasatch mountains of Utah, seventeen people met to talk, ski, relax, and try to find common ground—and of course, to eat. What emerged was the Agile ‘Software Development’ Manifesto. Representatives from Extreme Programming, SCRUM, DSDM, Adaptive Software Development, Crystal, Feature-Driven Development, Pragmatic Programming, and others sympathetic to the need for an alternative.

Excerpt from the History of the Agile Manifesto


AGILE MANIFESTO

Individuals and interactions over processes and tools

Working software over comprehensive documentation

Customer collaboration over contract negotiation

Responding to change over following a plan


That is, while there is value in the items on the right, we value the items on the left more.

AGILE MANIFESTO






Where will people go to access the information?


Does The Person Who Needs It, Have It?

If documentation

is not at someone’s

fingertips, they are more

likely to make assumptions.


Email with link to requirements & invite to meeting


Notification Meeting Has Been Rescheduled

RESCHEDULE

D


Requirements Lost In Email


Readily availableEasily accessedLatest updatesEasy to share

Where…the place that makes the most sense!


Data Management System or Document Library


Technology is the Application of Science


State the Problem

Describe The Method

Test the Hypothesis

Display The Results

Draw Conclusions


Prewriting

Drafting

Revising

Proofreading

Delivering/Publishing


Identify the Problem or Opportunity

Define

Understand the Audience, Method, & Format

Design Outline, Draft, & Revise

Draft

Proofread, Review, & Deliver

Finalize

The Technical Communication Process


Preparation & Planning Is The Key To Success!

Surgery does not begin with a cut

Cooking does not begin with a fire

Survival does notbegin with a disaster


Identify the Problem or Opportunity

Define

Understand the Audience, Method, & Format

Design Outline, Draft, & Revise

Draft

Proofread, Review, & Deliver

Finalize

The Technical Communication Process


Define: Get Up To Speed

Document AnalysisInterface Analysis InterviewsJob Shadowing


Define: Understand The Request


Design: FormatShorter Attention Span


Design: Format

Average person can read ~200 words per minute of casual writing with an ~85% retention.

That same person will take 50 to 75 words per minute to retain 85% of technical documentation.


Design: FormatAnalogy: Lord Of The Rings


Design: FormatIt’s About Technical Communication


Design: Format


Layout is cleanWhite space is deliberateInformation is well organized.Sections or referenced items are clearly labeledIt is to the pointIncludes graphics, images, or samples

Design: Format: Guidelines


Traditional ParagraphNon Traditional

Design: Format


Design: Format: Traditional Paragraph

Document

Wiki

Website


Design: Format: Non-traditional

InfographicOr

Presentation

Video/Vlog

Audio

Interactive


Agile Value: Working software over comprehensive documentationNOT Working Software instead of any documentation

Design: Format: Documentation Lite

No where in the Agile, Scrum, or Lean processes does it state, “No more documentation.”


Design: Delivery Method

Traditional - ParagraphDocumentWikiBrochure Style Website

Non-traditionalAudio or VideoPresentationInteractive Application


Draft

Outline Compose Revise


Why Do We Need An Outline?


Order & Develop Ideas

Categorize & Organize Information

Identify Missing Information

Save Time & Avoid Writers Block

Draft: Outline


Story Boards Make Great Outlines


Type Directly Into Your Document


Draw With A Smart Pen


OCR Optical Character Reader


Speech to Text | Dictation


● Why Technical Documentation & Communication Are Vital To Any Project

● How To Turn Complicated Ideas Into Simple, Lean & Agile Communication

● How To Avoid Common Pitfalls & Mistakes

Did We Pass Our Acceptance Criteria?


u [email protected]

u http://www.central-indiana.iiba.org

http://www.central-indiana.iiba.com/


Where Can I Learn More About CommonSensical Approach?Website: www.CommonSensicalBA.comCourses: https://commonsensical-ba-academy.teachable.com

https://www.udemy.com/user/deena-chadwick/ Books: Available Through Amazon, Kindle, Nook, & iBooks

http://www.commonsensicalba.com/

https://commonsensical-ba-academy.teachable.com/

https://www.udemy.com/user/deena-chadwick/

COMMONSENSICAL TECHNICAL DOCUMENTATION - IIBA ...

Documents

Transcript of COMMONSENSICAL TECHNICAL DOCUMENTATION - IIBA ...