From Technical Writing to Information Development

1
From Technical Writing to Information Development

• Presented to
• Society for Technical Communication
• November 17, 2004
• Alan Cline
• Carolla Development, Inc.
• www.carolla.com

2
Agenda

• Who is Carolla Development?
• From Technical Writing to Information Development
  
• Information Domains and Technical Writers
• Sample Domain Requirements Elicitation
• Problems with Requirements collection
• Techniques for Requirements collection
• Sample documents
• Standard Tools (de facto) Used.

3
Who is Carolla Development?

• Process engineering for software development
• Project management, requirements collection
• Technical writing is crucial to good software
  development
• Tech writers need to expand skills to new market
  needs and technologies
• Carolla trains technical writers to be info
  developers (business analysts).

4

• This is not your
• Remington typewriters
• profession anymore.

5
Technical Writing as It Was

• Major output documentation culled from
  development or operations team
• Procedures and standards manuals
• Operations manuals and run-books
• User manuals that get quickly out-of-date as
  application changes
• Primary tool word processor
• Contribution to development process rare or
  after-the-fact.

6
But

• Printed manuals for applications are being
  replaced with online help
• Web pages, HTML and XML are prolific for content,
  databases, and programming
• Interactive graphics and sound replacing static
  hardcopy artifacts
• Technologies providing new tools and new skills
• Simple data repositories being replaced by more
  holistic knowledge management.

7
Information Development as It is Becoming

• Business needs driving better development
• Better development requires better requirements
  and better QA
• Offshore outsourcing driving stand-alone
  (encapsulated) requirements
• Better artifacts needed during development, not
  after, that can drive information flow
• Clear, unambiguous, and objective writing needed
  for business reqments (use cases)
• Modeling artifacts are becoming vogue.

8
Information Domains

• Best-practice development uses successive
  knowledge refinement (risk curve)

9
(No Transcript)
10
Information Domains

• Best-practice development uses successive
  knowledge refinement (risk curve)
• Project initiation needs objective facilitation
• Requirements processes need clarity and
  disambiguation to build good specs
• QA processes, e.g., technical reviews, need
  objective documenters perspective and
  facilitation.

11
Why Tech Writers Make Good Information Developers

• Experts in communicating clearly and
  unambiguously
• Experienced at learning, analysis, and
  re-explaining new concepts
• Experienced at learning new tools quickly
• Can provide objective view as part of development
  or QA team
• If people-oriented, can provide independent
  facilitation skills
• Foreign values from foreign cultures.

12
Sample Domain Requirements Elicitation

• The greatest source of (and impact on) product
  defects

13
(No Transcript)
14
Sample Domain Requirements Elicitation

• The greatest source of (and impact on) product
  defects
• Customers often dont know or cant express what
  they want (context-dependency)

15
(No Transcript)
16
(No Transcript)
17
Sample Domain Requirements Elicitation

• The greatest source of (and impact on) product
  defects
• Customers often dont know or cant express what
  they want (face-of-the-cow dependency)
• Customers (subjective) expectations and
  perspectives bias success and absolute meaning
  (blind men dependency)

18
(No Transcript)
19
Sample Domain Requirements Elicitation --
continued

• Requirements are often collected non-rigorously
  and without validation
• Requirements often collected by solution-oriented
  thinkers yielding premature designs
  (solution-fixation)
• Requirements are written poorly and in an
  ambiguous mediumnatural language

20
Ambiguity as Major Problem with Specifications

• TIME FLIES LIKE AN ARROW.

21
Sample Techniques For Requirements Collection

• Project Initiation Business Abstracts and
  Project Abstract
• IEEE Specifications and Use Cases

22
(No Transcript)
23
Use Cases

• Are user transactions or scenarios that define
  how the user interacts with the system
• Contain non-design-centered business rules of the
  problem domain in rigorous structured English
• Define a unit of work for predictable time and
  effort estimates
• Are easily validated for completeness and
  correctness with business models
• Drives design, test cases, and user documentation
• Sample use case (ATM withdraw transaction).

24
Sample Techniques For Requirements Collection

• Project Initiation Business Abstracts and
  Project Abstract
• Use cases and IEEE Specifications
• Facilitation JAD and requirements collection,
  use case prioritization, Delphi consensus
• QA formal technical reviews, independent
  perspective (5x5 model)
• Elephant model Managers, developers, testers,
  customers, and documenters.

25
Tools

• RoboHelp for online help integrated into
  applications
• DreamWeaver and Macromedia Flash for
  sophisticated multi-media webpage development
• MS Front Page for HTML, and XML editors
• Visio or Framemaker for graphics (modeling
  artifacts)
• Version control tools (CVS) for managing project
  documents
• Beware A fool with a tool is still a fool.

26

• QUESTIONS?
• acline_at_carolla.com
• www.carolla.com

27
Develop the Project Abstract

• Merge stakeholders descriptions (business
  abstracts) into a single statement
• Define project mission with the executive goal
• Define project responsibilities as success
  criteria
• May contain time and cost estimate from the
  project manager
• Sample business and project abstract.