Pragmatic Artifacts Royce 6.4 Scott Nester

1
Pragmatic ArtifactsRoyce 6.4Scott Nester
2
Common Problems With Documentation

• Time wasted developing, polishing, formatting,
  reviewing, updating, and distributing
• Filled with ad hoc text and makeshift graphical
  representations
• Conventional languages were cryptic and
  unstructured
• Tangible but misleading indicators of progress
• Quality of documents became more important than
  quality of information contained within them
• Lengthy documents which were perceived to show
  progress, often resulted in an increase in scrap
  and rework later in the work cycle

3
No Language Understanding

• People want to review the information, but dont
  understand the language of the documentation
• Most resist learning any new languages or
  notations
• Many ask for separate documentation in plain
  English
• This unwillingness to change often leads to and
  increase in cost and time without adding any
  value to the project

4
No Access To Tools

• People want to review the information, but dont
  have access to the tools
• Example Project diagrams are done in Visio, but
  not all participants have access to Visio
• This leads to an increase in cross-documentation,
  which adds time and cost to the project
• Standardized tools, such a Adobe Acrobat and web
  browsers are making document exchanges much
  smoother

5
Documents Must Be Thorough

• Words should be spelled correctly and acronyms
  should be identified and explained
• Increased clarity will result in increased
  productivity, quality, and understanding
• Increased readability and self documentation can
  also improve quality
• Eliminating documents that are not used can
  streamline the project

6
Electronic Artifacts Are Easily Changed

• Paper documents are tangible, static, and
  persistent
• Hardcopy is still a preferred method because some
  are slow to adopt electronic forms
• Electronic documents can be changed and updated
  informally
• Paper is perceived to be stable, while electronic
  forms can be volatile
• This is slowly changing as electronic forms are
  becoming more common and accessible

7
Always Remember

• Software is the primary product
• Documentation is merely support material