Documentation Metrics Tharoor

8/8/2019 Documentation Metrics Tharoor

1/20

Measuring quality of writingMay 2007

Documentation

Metrics


2/20

What&

Why-M

etrics

Definition:Metrics are quantitative measures that helps

the team gain insights into the effectiveness

of the project within the process framework.

Metrics are analyzed by collecting data onquality and productivity.

Types:

Schedule Vs Effort

Productivity

Document Quality


3/20

Sched

uleVsE

ffort

Relating to staffing / resources

Schedule-related (estimating, milestones)

Rework, iterations

Predictability

estimated value actual value

actual value

Complexity

Effectiveness/timeliness of changeadoption

Risk assessment

Lessons learned


4/20

ProductivityVsSkill

Skill of user

On the job experience

1 year

1-3 years

3 5 years New Technology

Change of Domain

Rework owing to poor quality source


5/20

Produc

tivityFactors

Fresh Development / Enhancement /

Maintenance Text Vs graphics

Source creation method (team, SME)

Source provider experience level

Communicator experience level

Source quality

Product maturity

Technology maturity Content technical complexity

Production process & Automation


6/20

ProductivityMe

asures

Volume of documentation Overall

cost over time

Number of documents completed Cost

per deliverable

Time to complete a page Cost per

member

Savings per page ($) Cost per page

Cycle time in days

On-time effort - Cost benefit analysis


7/20

Factorstocheck

quality

Appraise/ Evaluate document quality

Create Checklist

Compare two different documents

Rate the documents

Internal / External / Benchmark

against competition

Rating Vs Effectiveness


8/20

DocumentQu

ality

Deployment

Content

Readability Navigation

Layout


9/20

De

ployment

Locate and open document

Find the document

Proper Naming Convention

View and accessibility

Environment

View easily, access speed and print

Secure

Appropriate read/write instructionsView / Modify accordingly


10/20

Content

Document the current system

Based on changesNeeds to be current

Version Control Effective Configuration management practices

Ensure latest version available

Metadata Appropriate information about document

A text document's metadata may containinformation about

Length of the article

Author

When the article was written? A short summary


11/20

Content

Metadata sample

Overview The background and a short overview of the document.

Considerations Any additional information of relevance to this document.

Definitions Any terms specific to this document.

Purpose The reason for or end result of the document.

Scope The areas covered by this document.

Related Material Any other extent documents that may be of relevance tothis document.

Approval The personnel responsible for approving or modifyingthis document.

Responsibilities The roles associated with this procedure and theirresponsibilities.

Tracking How is this document tracked to completion?

Records The files and folder that pertain to this document and theirlocation.


12/20

Re

adability

Intelligent content

Clear, Precise and Concise

Easy to comprehend

Simple to complex

Grammar / AmbiguityError free

Style

Consistent throughout

Jargon

Avoid or explain where required


13/20

Navigation

Navigable Table of Contents (TOC)

Get to section of interest

Search through

Indexed or full text search

Header / FooterAppropriate indications

Reference pointers

Provide reference to external links in text

Step wise procedures

Numbered task list to paragraphs


14/20

Naviga

tionC

ontd

Structure InformationReader perspective

Task oriented How to print document?

Logical contiguous stepsSteps that user follows

Defined stepsLead in heading -> consistency within

Role based task listAvoid ambiguity in role.

You/She/He

More references cross referDocument expected, refer when required


15/20

Layout

Look and feel

Layout and formatting coherence

Avoid many colors, different fonts

Elements

Fonts for print documentation /online help

Symbols

Consistent throughout the document

Headings

Labelled and applied properly

Diagrams / Screen dumpsRight place and referenced correctly


16/20


17/20

Metrics

Determ

inants

Factor Description

Document size Print: # of pages

Online: # of topics

Production level New: create content, edit, format

New: content provided, edit, format

Update: add some new content; edit, format

Update: edit, format only

Complexity Low Medium High

Format Microsoft Word, Microsoft Visio, HTML

TemplateRequirements

New template

Existing template

Revise template with documentNo template


18/20

Metrics

Determ

inants

Factor Description

Graphics None

< 5

5-10

> 10

Delivery Channel Print/PDF

Online (HTML, CBT)

Word document

Multiple formats

Review Cycle # reviewers/stakeholders

Full reviews required (content/structure/proof)

Content reviews only

Proof only (spelling, grammar)


19/20

AttributesofDo

cument

Quality

Attribute Unit of measurement

Information is easy to find headings/page

Index is appropriately sized index hits/page

Sufficient examples are used to illustratethe topics

examples/page

Sufficient illustrations/graphics are usedto illustrate the topics

illustrations/page

Glossary entries (if any) arecomprehensive, clear, and consistent

glossary entries/page

Reading level is appropriate for thedefined audience and purpose

Flesh-Kincaid index

Grammar, syntax, spelling, and

punctuation are correct

errors/page

Passive voice is used appropriately andonly as necessary

percentage of passive-voice sentences

Illustrations/graphics are effectivelyplaced

percentage of exhibits within sight of butafter cross-reference


20/20

Credits

Source

HCI journal

Documents

Documentation Metrics Tharoor