1 of 49

Let's bring science into technical writing

—�Lana Novikova, Writerside, JetBrains

2 of 49

Who is there?

—

Technical writer with 10+ years of experience
Self-nominated docs-as-code evangelist
Mentoring newcomers in the tech writing field and teaching IT students technical communication
Developing product for documentarians by documentarians #Writerside
Learning neurobiology, cognitive psychology, and andragogy in a spare time

3 of 49

What will be going on?

—

I will try to match the tech writing best practice with the science concept it is based on

No plans to retell you the whole scientific books

4 of 49

All we need is basement

—

JetBrains: The Drive to Develop

—

5 of 49

All we need is basement

—

6 of 49

All we need is basement

—

What is common sense is not just a common sense?

7 of 49

All we need is basement

—

8 of 49

All we need is basement

—

9 of 49

“The Science part”

—

JetBrains: The Drive to Develop

—

10 of 49

Writing process

—

11 of 49

Writing process

—

Defining what a user will accomplish to the end of the tutorial

12 of 49

A proper tutorial

13 of 49

A proper tutorial

14 of 49

Learning objective

—

What we do: Define what a user will accomplish to the end of the tutorial
What is it based on: Learning objective

Learning objectives articulate what learners should be able to do as a result of the instruction
Tutorials as a learning material must be driven by learning objectives

Origin: andragogy and theory of learning

Read more:

Jonassen and Tessmer (1996) Learning Outcomes-Based Taxonomy
Kemp, J.E., Morrison, G.R., & Ross, S.M. (1998). Designing effective instruction, 2nd ed. Upper Saddle River, NJ: Merrill

15 of 49

Learning objective

—

Origin: andragogy and theory of learning

Read more:

Jonassen and Tessmer (1996) Learning Outcomes-Based Taxonomy
Kemp, J.E., Morrison, G.R., & Ross, S.M. (1998). Designing effective instruction, 2nd ed. Upper Saddle River, NJ: Merrill

16 of 49

Learning objective

—

Origin: andragogy and theory of learning

Read more:

Jonassen and Tessmer (1996) Learning Outcomes-Based Taxonomy
Kemp, J.E., Morrison, G.R., & Ross, S.M. (1998). Designing effective instruction, 2nd ed. Upper Saddle River, NJ: Merrill

17 of 49

Learning objectives must be defined using action verbs�—�

Apply Execute�Operate Solve�Use Implement�Develop�Compute

Apply

Analyze

Evaluate

Create

Analyze�Inquiry�Organize�Distinguish�Select

Assess Test �Compare�Validate

Develop Produce�Generate�Modify�Specify�Create

18 of 49

Writing process

—

Adding in-page TOC and breadcrumbs to display progress

19 of 49

Progress tracking

20 of 49

Progress tracking

21 of 49

Checklists

22 of 49

Zeigarnik-Ovsyannikova effect

—

What we do: Adding in-page TOC and breadcrumbs to display progress
What is it based on: Zeigarnik-Ovsyannikova effect

Incomplete tasks remain in a person's memory longer than completed.
Unfinished task creates compulsive thoughts aimed at returning to the task and finishing the interrupted action.

Origin: Psychology

Read more:

Zeigarnik, Bluma (1938). "Das Behalten erledigter und unerledigter Handlungen" [On Finished and Unfinished Tasks]

Zeigarnik effect occurs when an activity that has been interrupted may be more readily recalled.

In the course of the experiments, Zeigarnik asked the subjects to solve several tasks in a certain amount of time. In the process of solving tasks, half of the subjects were not allowed to complete some of the tasks, citing a lack of time.

Zeigarnik then asked all of the subjects to list the tasks they had memorized. It turned out that among the memorized tasks, the ratio of completed to incomplete tasks averaged 1.9. That is, those subjects who were interrupted during the task recalled almost twice as many tasks.

It means people remember unfinished or interrupted tasks better than completed tasks. So we use it a lot in UI UX design and software development, when we for example show how many steps left, place a progress bar, breadcrumbs, or checklist. It is used a lot to onboard users faster and effectively as they will tend to get back to the unfinished flow. Progress trackers which inform users of how close they are to complete a task. For example, when users see a message like "Your profile is 64% complete", they are more likely to spend a few minutes on providing all missing details.

23 of 49

Zeigarnik-Ovsyannikova effect

—

24 of 49

Writing process

—

Use parallel constructions/keep consistency

25 of 49

Parallel constructions

The best way to make your reader feel comfortable is to establish a pattern for all of the information. All of the paragraphs in the same section should have the same voice and mood. All of the topics should follow the same pattern. All the documents should have the same structure. This eliminates the drama from the writing but, let's face it, when you need information now, who needs drama?

For example, if your document has a chapter that starts with a heading, a brief introductory sentence, and a list of the information that is in the chapter. All chapters should have that structure. Otherwise, it is very obvious that you have multiple authors or a totally scatterbrained person writing your document. The bonus is that, once you establish a pattern, it is easier to write as well as read.

So decide what do you using like gerund, infinitive, or certain clauses and stick to it.

26 of 49

Cognitive load

—

What we do: Use parallel constructions so that user will be able to skim through the document
What is it based on: Cognitive load

Similar constructions and repeated experience — idiomaticity
Minimize cognitive load:

Parallel list items
Parallel grammar constructions

Origin: Cognitive psychology

Read more:

Sweller, John (April 1988). "Cognitive Load During Problem Solving: Effects on Learning". Cognitive Science. 12 (2): 257–285.

27 of 49

Cognitive load

Difficulty in learning something new

The use of mental resource that doesn’t help to achieve the goal

The processing, construction and automation of schemas.

Intrinsic

Extraneous

Germane

The less intuitive and familiar is something, the less brain power it needs to process.

There are three type, the first one is intrinsic which means internal. It vary from person to person and depends on the cognitive styles (our individual ability to learn and soak information), the second is extraneous (external) cognitive load. unnecessary information is anything that uses mental resources without helping the user to complete their goal. As you may be able to tell, extraneous cognitive load is the easiest to reduce by avoiding redundant links, unclear terms, non-parallel constructions, non consistent formatting and many more. ��There are three types of methods to address the measure of cognitive load: subjective rating, performance-based measures and physiological measures. So we can evaluate the difficulty using the empirical methods.

28 of 49

Writing process

—

Make lists not longer than 7+-2 (5) elements

29 of 49

Lists up to 5-7 elements

30 of 49

G.Miller’s Magic number

—

What we do: Keep lists not longer than 7 (5) elements
What is it based on: Miller’s Law

Now it is 5+-2 due to digital dementia effect

Origin: Psychology and neurophysiology

Read more:

Miller G. The magical number seven, plus or minus two: Some limits on our capacity for processing information. Psychological Review, 63(2), 81–97.

31 of 49

Writing process

—

Use templates and consistent formatting

32 of 49

Using templates

33 of 49

Cognitome and the cloud of meanings

—

What we do: Use templates and same formatting for same type of elements
What is it based on: Cognitome and the cloud of meanings

Cognitome is a neural hypernetwork, all meaning are connected with each other, but we load them not by one, but in a complex
People seek for similar meanings that exist in their cognitome.

Origin: Neurophysiology

Read more:

Anokhin K.V. The Cognitome: Seeking the Fundamental Neuroscience of a Theory of Consciousness

34 of 49

A science concept

—

What we do: <Best practice>
What is it based on: <A science concept>

<Item 1>
<Item 2>

Origin: <SCIENCE>

Read more:

<References to the science works>

A Slide template

35 of 49

Writing process

—

Vary sentence length and watch it

36 of 49

Vary sentence length

37 of 49

Parcellation and inner speech studies

—

What we do: Vary sentence length to add rhythm and watch it
What is it based on: Parcellation or dislocation (in Charles Bally terms) and inner speech studies

Parcellation is when an author divides one coherent sentence into several to emphasize intonation and add dynamics.

Origin: Applied linguistics

Read more:

Concise, Scannable, and Objective: How to Write for the Web by John Morkes and Jakob Nielsen (1997) Abstract Studies
Dr. Kristi Siegel Varying Sentence Length

In writing, rhythm is defined by punctuation and the stress patterns of words in a sentence. Reading becomes monotonous when all sentences are similar in length. To create a pleasant reading experience, vary the length of your sentences.

Short sentences make readers pause. So, use short sentences to shine a spotlight on your key points.
Long sentences take readers on a journey and speed up the reading experience.

Scientists have proven that your readers can sense the rhythm in your writing. Even when they aren’t reading your copy aloud, they can hear its rhythm because they listen to their inner speech. In the 1990s, neuroscientists used functional neuroimaging to demonstrate that areas such as the left inferior frontal gyrus (Broca’s area), which are active when we speak out loud, are also active during inner speech. Furthermore, disrupting the activity of this region using brain stimulation techniques can interrupt both “outer” and inner speech.

Author Mike Markel suggests that an average of 15 to 20 words is the most effective for technical communication. However he also advised against writing sentences that were all the same length

“Sometimes sentence length affects the quality of the writing. In general, an average of 15 to 20 words is effective for most technical communication. A series of 10-word sentences would be choppy. A series of 35-word sentences would probably be too demanding. And a succession of sentences of approximately the same length would be monotonous.”

There’s almost a one-to-one correlation between sentence length and understanding, according to research by the American Press Institute. The research, based on studies of 410 newspapers, correlated the average number of words in a sentence with reader comprehension.

The study found that:

With average sentences of 8 words or less, readers understood 100% of the story. (Downside: Copy might sound as if it had been ripped from a Dick and Jane book.)
At 14 words, they understood 90% of the information.
At 43 words, they understood less than 10%.

38 of 49

Let’s wrap up

—

JetBrains: The Drive to Develop

—

39 of 49

40 of 49

41 of 49

42 of 49

43 of 49

44 of 49

45 of 49

46 of 49

Takeaways

—

Technical writers have a lot to lean on in various areas: cognitive science, psychology, neurophysiology, applied linguistics.

47 of 49

Takeaways

—

Technical writers have a lot to lean on in various areas: cognitive science, psychology, neurophysiology, applied linguistics.
We often think that our best practice are based only on our experience

48 of 49

Takeaways

—

Technical writers have a lot to lean on in various areas: cognitive science, psychology, neurophysiology, applied linguistics.
We often think that our best practice are based only on our experience
We have shorter distance to a user and can prove our hypotheses -> HeatMaps, interviews

49 of 49

Let’s stay in touch

—

@_Unsolved_

Come to the writerside

@svetlnovikova

@lananovikova10

https://lananovikova.tech/

@svetlana-novikova

jetbrains.com