TC Bootcamp session4 June2018€¦ · (c) 2007 -2018 Leah Guren (Cow TC) for STC 2...

(c) 2007 - 2018 Leah Guren (Cow TC) for STC 1

1

Welcome to TechComm Fundamentals Bootcamp, Session 4

TechComm Fundamentals Bootcamp, © 2017 Leah Guren

Homework Issues

� Again, where was the analysis?• Who is the client?

• What are they trying to solve with this info? How are

they monetizing it?

• Who are the users, how do they get the info, and

what are they supposed to do with it?

� Analysis errors:• confusing client and user (for example, giving me a

persona for the client)

• not understanding internal info vs. user-facing

content

2



Homework Issues

� Useless fluff:• “studies suggest”

• “follow these directions”

• “ensure”

� Writing style problems:• passive voice

• vague modifiers (for example, frequent)

• acronym first, then spell-out

• punctuation errors

3


Homework Issues, cont.

� Inverted structure:• start with high-level concept, then go to details

• that is, RSI first, then examples of RSI

� Incorrect or incomplete info:• you cannot promise to prevent RSI!

• what is the correct position of chair, keyboard, etc.?

� No graphic (impossible to solve without one).

4



Homework Issues, cont.

� Bad hazards

WARNING: Failure to follow these instructions

may result in a pressure on a nerve in your wrist

or tendon injuries.

Do not type with your wrists

resting on the desk. Incorrect

positions can cause injuries.

WARNING

passive voice, signal word not separated from text, no clear “do/do not” statement

5

� Questions?

Planning and Managing TC Projects

Six tips for a smoother process7

6



What makes the difference?

Bad Project

Management

Good Project

Management

7


Everyone assumes you know this,

� You need to manage your own work,

even if you aren’t a manager.

� Most project failure occurs from lack

of up-front analysis and poor

communication.

� It is all about asking the right

questions and analyzing data before

you begin!

� Remember, this is internal info and

your own work plan, not anything the

end-user ever sees!

8



Prepare, organize, and communicate.

You need to collect the right info and act on it.

1. Figure out the scope of the project (UI impact).

2. Identify stakeholders and their key concerns.

3. Determine the correct deliverables.

4. Use a tool to plan and track project (Gantt chart).

5. Communicate clearly and adjust throughout.

6. Lessons learned at end for improvement.

9

First, a word about development methodologies7


Waterfall vs. Agile Development

� Traditional (waterfall) development:• entire version of product and docs are created before

review

• project may be many months or even over a year

� Agile development:• small chunks developed, tested, reviewed

• docs on per-topic basis

• sprints are usually 2–3 weeks

• planning and management must be scaled down

accordingly

10

Where applicable, Agile hacks are labeled like this.



1: Figure out the scope.

� Existing product or new?• version number (4.0 = major release; 4.2 = intermediate

release; 4.27 = minor release)• trick: look at UI impact, not R&D effort

� Look at prototypes.

� If totally new, is there a comparable product?

If a sprint doesn’t use traditional version numbers,

consider it a second level (intermediate release), like 4.2,

if it is adding a feature, or third level (minor release), like

4.2.1, if it is improving a feature.

11


2: Identify stakeholders.

� Who is involved?• product manager, key R&D• marketing• regulatory• What other stakeholders can you think of?

� Find out their key concerns:• don’t assume they care about UX• remember, you have to address the needs of your

client as well as the needs of the users!• What are some other possible concerns?

12



3: Determine the deliverables.

� Remember your audience analysis? • what do they need to do?

• where do they need to do it?

• therefore, what do they need to know?

• and what is the most useful format?

� (We’ll talk more about deliverables in a bit7)

� Write a project proposal:• what you can deliver (UG, online Help, etc.)

• approximate scope of what is covered

• why this focus solves key concerns of stakeholders

• goal: avoid surprises

Limit proposal to a simple email identifying topics only.

13

TechComm Fundamentals Bootcamp, © 2017 Leah Guren14



4: Use a tool to track.

� Identify:• resources (writers, editors, other content developers, etc.)

• tasks (break project down into manageable tasks)

• timeline

• task dependencies

• who does what, etc.

� Use a Gantt chart to visually represent this (tasks listed vertically, timeline shown horizontally).

� Identify resource problems before you start:• over- or under-use

• conflicts

� Track as you go (keep it up-do-date).

Simplify to topics and 1- or 2-day measurements. Monitor

but don’t update.

15

TechComm Fundamentals Bootcamp, © 2017 Leah Guren16


17

https://www.teamgantt.com/blog/gantt-chart-example/


Still not clear how to start?

1. Brainstorm all tasks:• what, how long

• break down into subtasks if necessary

2. What are the relationships of the tasks (for

example, what has to be done first)?

3. Who does what?

4. Where are the handoffs?

5. Look at the overall time scale (work backwards

from a deadline).

18

Let’s do an example together (friend’s wedding)7



5: Communicate clearly and adjust.

� Think of every critical milestone for reviews:• communicate clearly what you need the reviewer to do7

• 7and how and when

� Communicate clearly and regularly with your client:• project status

• any changes

� When there are problems, be ready to adjust plans and document changes in your process.

� Remember, poor communication is a main cause of project failure.

Don’t let the daily standup exclude TechPubs.

19


6: Conduct a lessons learned session.

� Aka post mortem.

� At the end of a project, review the process.

� Identify:• what went wrong and how can you fix it• what went right and how can you repeat it

� Think about the process rather than blaming people.

� Learn and improve:• clients hate seeing the same mistakes over and over• ditto for me!

Shorter turn-around, no time to wait.

20



Managing Projects: Review

� Always take the time to collect data and

understand the project before starting.

� An aimless, unplanned project usually fails!

� Always think of what your client wants and

what your users need!

21

22

Deliverables

What are the most common TC

deliverables?



Common Documents

� Task-based documents:• user guides or manuals

• installation manuals or quick-start guides

• troubleshooting guides

• maintenance manuals

� Feature-based documents:• product manuals

• release notes (aka Readme)

• specs and design documents

• API manuals

� Mixed:• online Help

• tutorials (instructional design)

• white papers

23


Focus on Using (should be task-based)

� User guides or manuals:• guide: SW, general products

• manual: HW, more technical

� Installation guide or manual:• introduction: product overview, doc conventions

• site preparation

• unpacking and installing

• calibrating and troubleshooting

� Quick-starts:• good for small electronics or appliances

• contain basic orientation, setup, and most common

procedures

24



Focus on Using, cont.

� Maintenance manuals:• complex hardware or software

• specialized audience

� Troubleshooting guide:• may use flow-charts or tables for diagnosis

• may contain extensive reference in addition to

procedures

• specialized audience

� All can be any format (online, print, PDF, etc.).

25


Focus on Product Concepts (mostly feature-based)

� Product manuals:• complex products that require large amounts of

background conceptual knowledge

• focus on understanding product

• not usually needed!

� Release notes:• simple format with last minute info, focusing on �

(change delta) about a version

• contains: version number, new features,

modifications, fixed bugs, known bugs, may include

history

26



Special Predevelopment Docs

� Specs and design docs:• written by R&D for R&D

• entirely feature-based, describes how product will function

• internal documentation for developers, testers, managers, etc.

� API (application programming interface) docs:• written for R&D

• describes code so that software or devices can exchange data:• web = SOAP (Simple Object Access Protocol), RPC

(Remote Procedure Call), or REST (Representational State Transfer) APIs

• hardware = native APIs• SW = library APIs

• requires knowledge of programming

27


Online Help (aka User Assistance)

� SW only (esp. context-sensitive).

� Just-in-time documentation while using product.

� Mix of feature-based and task-based:

• must describe each dialog box functionally

• can also include procedures, troubleshooting

� End-user documentation.

� Many formats (WinHelp, HTML Help, Web Help, Java

Help, FlashHelp, .NET Help).

� Many HATs available (RoboHelp, Flare, Doc-to-Help).

28



Tutorials and Training Material

� Appropriate for very complex products.

� They teach and develop skills through lessons.

� Requires understanding of ID (instructional

design).

� End-user documentation.

� Format may be interactive online, print,

softcopy, etc.

29


White Papers

� Often written by Marcom, but should be TC.

� Focus on highlighting a company’s expertise.

� Primarily descriptive:• introduce a problem

• discuss previous solutions and their drawbacks

• introduce company’s product or service as it solves

the problem (last 20%, max)

� Very simple and short.

� Should not sound like a brochure.

� Format may be print or softcopy.

30



Look out!

� There are many more:• quick reference card

• project reports

• PowerPoint presentations

• company website content

• company P&P (policies and procedures)

• newsletters

• company social media (FB pages, blogs, tweets)

• project wikis

• ???

� Do not forget GR#5! (Your client may not know

what these mean!)

31


Session 4: Discussion & Homework

� Moodle discussion topics:• Have you ever completely misunderstood a

project by failing to collect the right data?

• What is one project planning technique you

could apply to any project (not just TC)?

• Which of these deliverables interest you?

Scare you?

� Homework: Create a Gantt chart for a

project.

32

TC Bootcamp session4 June2018€¦ · (c) 2007 -2018 Leah Guren (Cow TC) for STC 2...

Documents

Transcript of TC Bootcamp session4 June2018€¦ · (c) 2007 -2018 Leah Guren (Cow TC) for STC 2...