User:APaskulin (WMF)/Research

This page is a repository for various notes as part of my general research into technical writing and communication.

From Managing your Documentation Projects by Joann T. Hackos
“Quality lies in a well-managed process. Standards and good people, although useful, are simply not enough to sustain quality through many years and many different people and projects. Only with a sound process in place and people training in managing the process can quality be consistently produced.” xiii (I think the key emphasis here is “and people training in managing the process”.)

“Technical communication always seemed in those days to be at the end of the life cycle.” xiv

“You have focused your efforts on what is [easily] measured, rather on what is important although difficult to measure.” 10

“Without good management, even the best people will have difficulty producing work of consistently high quality. With good management, even less experienced or skilled individuals will have the opportunity to do the best work they are capable of doing.” 18

Hackos places a strong emphasis on project management in the description of the evolving publication process. For example, in level 2, Hackos calls out writers who “begin to function as project managers” (68). This evolves into level 3: “Every project has a designated project manager, although it is often one of the writers.” (68). In the absence of a dedicated project manager, project management tasks are often classified as undesirable glue work, so it's nice to see Hackos showing taking on these responsibilities as part of a demonstrated model of progressing organizational maturity.

For better quick referencing, I'd recommend these labels for the different levels:


 * Level 1: Independent
 * Level 2: Coordinated
 * Level 3: Structured
 * Level 4: Managed
 * Level 5: Optimized

The difference between level 3 and 4 seems to be mostly in the minds of others in the organization with writers taking on a user advocate role in the product development process.

From Basics of Qualitative Research by Strauss and Corbin
“attributes needed by qualitative researchers: appropriateness, authenticity, credibility, intuitiveness, receptivity, reciprocity, and sensitivity” 6

“Characteristics of a grounded theorist
 * 1) The ability to step back and critically analyze situations
 * 2) The ability to recognize the tendency toward bias
 * 3) The ability to think abstractly
 * 4) The ability to be flexible and open to helpful criticism
 * 5) Sensitivity to the words and actions of respondents
 * 6) A sense of absorption and devotion to the work process” 7

“persons act on the basis of meaning” 9

On the capitalization of team names
Should the names of teams and groups be capitalized in English? Is it "the design team" or "the Design Team"? Most English speakers seem to say that you should capitalize when referring to a specific group "the Design Team" and use lowercase when referring to a general type of group "a design team". But I've found a lot of debate about this and a lot of inconsistency in the way capitalization is used when it comes to any noun or noun phrase that refers to a specific entity.

Wikipedia says that capitonyms are “words which change their meaning between capitalized and uncapitalized usage”. There is a clear difference between "the design team" and "a design team" because of the difference in article. But is there a difference between "the design team" and "the Design Team"? In a strict grammatical sense, I would argue that there is no difference and lowercase is more correct. In a practice sense, there is a clear difference of importance. Even AP style, which is conservative about capitalizing names, capitalizes names that are "formal" or "not widely used generic terms". This is similar to the Wikipedia style guide that capitalizes "full names".

How formal is enough for capitalization? How uncommon? This ambiguity is the result of the fact that these proper names have slightly different characteristics from proper nouns. Proper names can include proper nouns, but they can also include common nouns or "the". When a proper name includes "the", Wikipedia classifies this a "weak proper name". Here are a few examples of inconsistent capitalization of weak proper names in English: "the pope", "the Queen" , "the Commission" , "the university"

In conclusion, I find that patterns of capitalization in English are being influenced by the expanding use of capitalization online for emphasis and irony. The result is a general shift towards capitalizing names that feel important or specific. When it comes to organizational documentation, team names are more likely than not to be capitalized. While I think this is ok for team names, we should be careful to not open the door to capitalizing anything and everything we think is important.

From Memory and Attention by Donald A. Norman
“If a person is asked to name what he has just seen, he stumbles, able to recall but a handful of items. In fact, the results of a large number of carefully controlled experiments indicate that humans can usually recall only a very limited number of items which have just been presented to them—from as few as four to, perhaps, ten items.” 85

“Meaningful material is relatively easy to learn, but we have trouble with isolated items.” 85

Skimming: “Erdmann and Dodge (1898) showed that in reading, for example, the eye assimilates information only in the brief pauses between its quick saccadic movements.” 86

“This process of increasing the memory span by efficient grouping of old items into new items, Miller called chunking.” 91

From Accelerate State of DevOps 2021
"Documentation doesn’t have to be perfect. Our research shows that any improvement in documentation quality has a positive and direct impact on performance.

Today’s tech environment has increasingly complex systems, as well as experts and specialized roles for different aspects of these systems. From security to testing, documentation is a key way to share specialized knowledge and guidance both between these specialized sub-teams and with the wider team. We found that documentation quality predicts teams’ success at implementing technical practices. These practices in turn predict improvements to the system’s technical capabilities, such as observability, continuous testing, and deployment automation." - 21

How to improve documentation quality: - 22-23
 * Document critical use cases for your products and services.
 * Create clear guidelines for updating and editing existing documentation.
 * Define owners
 * Include docs as part of the software development process
 * Recognize documentation work during performance reviews and promotions
 * Offer training on how to write and maintain docs
 * Automate testing for code samples and completeness
 * Provide style guides and writing guides

Further reading:
 * Quality metrics informed by existing research on technical documentation
 * The Value of Software Documentation Quality
 * Cost benefits and quality of software development documentation

From Everyday Information Architecture by Lisa Maria Martin
"The meaning and impact of the content tells us not only how to display it, categorize it, and label it, but also how to connect it into a functional, overarching system." - 57