Values represent characteristics or qualities of documentation that are important to readers, writers, and sponsors.

Value

Quality is value to some person.

Gerald M. Weinberg. Agile and the Definition of Quality

Values are desirable characteristics or qualities of things, ideas, activity patterns, and everything that actually has characteristics. Wiktionary defines value as the quality that renders something desirable or valuable.

According to ISO 9000:2015 quality is determined by matching a set of inherent characteristics with a set of requirements. The degree of the match determines the result of the quality assessment. Therefore value is strongly related to a group of people to take advantage of using a particular artifact. To address these groups we need to identify them according to the role they are playing in a given use case.

Value is a function of quality and cost. So, on limited resources, not all desired qualities are available in any amount. Priorities need to be specified by the stakeholders.

Qualities of Documentation

To define the values of documentation for roles of stakeholders we need to find desirable qualities of documentation or team communication. The list of quality attributes to documentation is quite extensive and overwhelming.

 

A sample of quality attributes for documentation:

  • accuracy
  • adequacy
  • authenticity
  • clarity
  • classifiability
  • clearness
  • completeness
  • conciseness
  • concreteness
  • confirmability
  • consistency
  • correctness
  • editability
  • honesty
  • integrity
  • objectivity
  • organization
  • preciseness
  • readability
  • relevance
  • retrievability
  • task orientation
  • timeliness
  • traceability
  • simplicity
  • style
  • understandability
  • usefulness
  • validity
  • visual effectiveness

To support teams seeking to create and maintain valuable documentation, we need to define a set of actionable qualities. Grouping is the first step to make qualities actionable. The second step is to make them more specific.

Qualities for Readers

Gretchen Hargis et al. organize the qualities by grouping them. They define three groups for readers of documentation:

  • Easy to find
  • Easy to understand
  • Easy to use

These quality attributes are associated with these groups.

 

While Hargis et al. use the term group to organize quality attributes, we refer to this groups as values. 'Easy to find' is therefore also a value of documentation that is addressed by maximizing the quality attributes organization, retrievability, and visual effectiveness.

 The selection of nine quality attributes may seem a little arbitrary at first. In their book Developing Quality Technical Information (Gretchen Hargis, Michelle Carey, Ann Kilty Hernandez, Polly Hughes, Deirdre Longo, Shannon Rouiller, Elizabeth Wilde) the authors show how other quality attributes relate or are actually part of these fundamental nine quality attributes. For each quality this book provides plenty information and examples on how to create documentation with these qualities.

We won't go into more detail here. For more information on this topic we recommend: Read this book! (smile)

Reducing the amount of quality attributes to nine and grouping them into three groups makes qualities easier to manage. Nonetheless creating quality documentation is an iterative process. The quality attributes also do not demand a specific process, may it top-down or bottom up, agile or not.

Qualities for Writers

Authors or a team of developers are also readers and therefore value the same quality attributes as readers. In addition to that the following values are relevant.

  • Easy to write
  • Easy to maintain

To make it easier to visualize the path to achieve these values, the following qualities are associated to these values.

Qualities for Sponsors

Sponsors not necessarily get in touch with the documentation. Therefore they seek these values for reades and writers only transitively. That is they seek to provide their consumers or customers and development teams high quality documentation to enhance the return of investment. They may also need to deliver documentation because of organisational, legal, or other issues.

Work in Progress ...

 

Currently we focus on qualities of interest to readers and writers.

This should for now only be a hint that there are more roles involved than those that actually get in touch with the documentation. 

Grouping qualities is the first step to make them actionable. But this first step is not enough. To make them really actionable we need to get more specific. We need to provide guidelines to follow in order to realize the values we desire. We call these guidelines principles.

Resources

More on documentation principles and documentation practices:

Principles
List of principles for agile documentation (mostly) derived from software development principles.
Practices
Practices to collaborate on agile documentation.