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.

"Write only the information the audience needs to perform the task, rather than all the information that the writer knows." 238

Hackos pursues an interesting strategy of detailed content specification prior to starting the work of writing. This would allow projects to be handed off between writers and provide a detailed history of the project goals.

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", "Ebola", "influenza"

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:

• 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

- 22-23

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

The concept of “information architecture” is very appealing. Much like “documentation engineering”, it borrows the language of something more concrete to make the work of maintaining words sound important and foundational. Information architecture seems to be a meeting place for user experience designers and writers, both groups finding this type of thinking essential to their work, although arriving from different starting points.

“Whatever our role, we are designers of information. Our choices alter the presentation and flow of human knowledge. We control how people find, understand, and use information in every facet of their lives. We must be very, very careful.” 1

The points Martin makes about information architecture are true, not only of structure and design, but of word choice, sentences, and paragraphs. “Every decision we make—or fail to make—changes the way the information is perceived” 17.

Martin starts by reviewing systems of organization. What’s interesting here is the broader distinction between grouping versus ordering, and their relative purposes. For example, “Alphabetizing isn’t for discovery—it’s for research.” 8 Usually with technical documentation, grouping is used as the primary means of organizing content, sometimes by content type (tutorial, reference, etc.), by feature, or by the task the user is trying to accomplish. Most frequently, you’ll see a mix of grouping strategies used in the same collection of content.

Within these groups, there are always places where things need to be ordered. Ordering in documentation can be done according to a sequence of steps (install before config), relative importance (required parameters before optional), likelihood of occurrence (primary use cases before edge cases), or frequency of access (cheatsheet before comprehensive reference).

Martin makes an interesting point about the experience of information online, in general: “Online, time is of the essence. What happens in the moment needs to be responded to in the moment.” 10

Martin makes the point that readability scores are not useful in isolation but can be helpful when looked at as trends within sections: “comparative readability”. Martin uses four readability scores as part of an audit: Dale-Chall, Flesh Kincaid Grade Level, Gunning Fog, and Smog Index. 33-34

“With all of this analytical nose-to-the-grindstone work, let’s not lose sight of why we’re doing it in the first place. It’s all so that future design and development decisions will be grounded in truth, rather than assumptions. They will be decisions that respect the contexts of your content and the contexts of your users.“ 35

Factors that shape categorization: The needs of the users, the goals of the business, the current state of the content, the strategic future of the content. 38-39

The section on user needs provides some useful shorthand for how to do user analysis, “Who is on the site? What are they trying to accomplish? What are their primary actions? What do they care about?” and “who’s visiting the site; what they want and need…, as well as the language you use to label it.” 39

One request I often get is for a “choose your own adventure” style information architecture. Are you an X? Click here. Are you a Y? Click there. Martin articulates the problems with this approach, mainly “Users are visiting to accomplish a specific task—not select an identity. Having to first self-select a label adds an extra step to their path.” 40 It is a heavy burden to ask a user to make an identity-level decision just to access information. Martin calls out verbs as a useful tool in mapping user tasks. Another key point that Martin makes that I often see is that audience-based navigation doesn’t clarify the point of view when talking about the audience: is this content for that audience or about that audience?

Sidebar on Conway’s Law: I hear a lot of talk about Conway’s Law. Most of it is along the lines of: we should adapt our communication structures to better reflect the system we want to produce. Interestingly, Martin declares that we should fight against Conway’s law, not give in to it.

Great guidelines for technical writing in general: Clarity, Specificity, Inclusivity, Consistency 51

I love the section about necessary pronouns. Sometimes I feel like pronouns appear and create this complicated story of “us” and “your” and “our” and “my”, divisions we don’t need to make. 54

On personal productivity

Over the past several years I've been experimenting with different ways to track my productivity at work. I've used GitHub issues, Trello cards, Google Docs, and, now, wiki pages to log my primary work activities week over week. Although it seems daunting and frankly looks a little ridiculous when viewed at scale, I've found this to be really helpful in understanding my progress over time. In addition to what I worked on, I wanted a way to capture how I felt doing the work. If I tracked which weeks felt more or less productive, could I increase the number of weeks that felt productive at the time and not just in retrospect?

I started ranking each work week on a scale of one to ten, ten being the most productive-feeling. This was interesting; I did start to see a consistent "shape" to the quarter with a somewhat predictable productivity trough mid-quarter. But this wasn't giving me any information about what was causing these fluctuations. At the start of the 2021-2022 fiscal year, I wanted to formalize an informal process of dividing my time between projects by percentage. To measure how well I was able to stick to these percentages over time, I started tracking roughly how many hours I spent on each project per week. This eventually expanded to tracking other data points like the number of hours spent in things like all staff meetings and doing professional development.

Note: Aside from the final percentages at the end of the quarter, I keep this data strictly private. I do not support mandatory time tracking for full-time workers. Fortunately, more and more organizations are moving away from the traditional hours-in-the-chair model of work to flexible schedules and output-based performance.

As I look at the data I’ve collected over the last two quarters, what have I learned about the ways I want to work? There’s a concept in psychology called a flow state. For example, in a video game, this could be a balance between challenge and ease that keep the experience fun and engaging for the player. On a perfect working day, there is a natural flow between tasks, a feeling of productivity more than a specific metric or list of completed tasks.

A key part of maintaining a flow state that enables the feeling of productivity is context switching. Individual daily work scheduling is the planning of context switches. For my next iteration of work tracking, I want to emphasize, not just the number of productive hours per day, but the number of context switches. Personally, my ideal number of context switches per day is between one and two.

What causes context switching? For example, let’s say I start out in the morning on context 1, and I get blocked by a question. I can ask the question on Slack and hope for an immediate response to continue in my current context, but this pattern is incompatible with the reality of timezones and globally distributed teams. Blockers are one of the main events that necessitate a context switch. Ideally, I would know when I am likely to encounter a blocker and incorporate that into my schedule, but that's not always possible.

The most disruptive cause of context switching is meetings. With globally distributed teams comes less flexibility in meeting times. Since I’m in Pacific Time, my meetings are predominantly clustered together in the morning, leaving me with time for focused work in the afternoons. On days with few meetings, I can schedule context switches to coincide with lunch, creating space for a clear mental break between contexts. On days with several hours of meetings, I can fill smaller gaps of time between meetings with professional development time. I may see a maximum number of context switches per day or I may see that context switching between certain projects in easier than others. I also expect some fuzziness around the separation between contexts.