Brutal tutorial : best practices for concise reads.

Philosophy

When reading tutorials on know-how, a range of readers want clear, concise instructional texts. Yet a large range of writers provide balanced, elegant texts. Brutal tutorials is a minimalist and instructional writing style to transmit a know-how the most efficiently possible.

“Minimalist writing isn’t just deleting content, it is writing to deliver a lot of value in as few words as possible. It is the conjunction between clarity and brevity.”
— Society for Technical Communication

Notes
Elegant writing is useful for various valid reasons, but we argue stylish turns are partly due to social statements and impairing efficient learning of know-how. Brutal tutorial has legitimacy to focus strictly on efficient learning.
Both styles need specific, delicate editing and multiple iterations for optimal result. Brutal writing is rapid, clear, straight to read. Elegant writing is longer, confusing at times, but pleasant to read.

Guide of style

Style’s best practices

• Simple, simple, simple
• Clean
  - avoid or remove fancy styles and turns which don’t transmit information.
• Concise
• Clear
• Consistent
• Logical writing : actions written in chronological order (avoid stylish inversion style)
• When subject is ambiguous, avoid pronouns, prefer repetition.
• Didactic typography :
  - bold: lowest section title, key learning points, key results
  - italic: names, brands
  - underline: links, conclusion

Content’s best practices

• Define objectives
• Define requirements
  | Requirements: Ubuntu +8 , web browser, Medium.com‘s account
• Workable and standalone examples
• Keep items as a whole (avoid slicing !)
• Comments in example (if the material allows it)
• Define vocabulary : concise lexicon, cheatseets.
  | Comparison queries: $eq, $gt,$gte,$in,$lt,$lte,$ne,$nin.
• Avoid final wrap up
  - if you need one, you didn’t wrote a brutal tutorial.

Instructional dialect

The instructional dialect is a minimalist writing style which chains actions and choices so to guide the reader to reproduce this chain of actions and choices faithfully. It adapts to the target public. Examples :

# Tutorial for non-techy 65y/o father who knows how to open Chrome
Open “Chrome” > In top bar: enter “Baby Otter” > Enjoy images.

Or sending a email with Gmail

Open Gmail.com : login > Inbox: click “Compose”
> Fields “To”, “Subject”, main text area: fill adequately > “Send” : click.

Core elements

A > B : change focus from A to B
B : action : on/in element B, do this action
B: action "text" : on/in element B, do action action on exact text text

Tips

Use comments conventions, indented lists (brutal ones, elegant ones if dependency is important), smart Unicode characters …

/* Comment ******* */   /* Comment ****** */   /* Comment ****** */  * China                 -China                 ├─┬ China
** Henan province       --Henan                | └─┬ Henan province
*** Zhengzhou           ---Zhengzhou           |   └── Zhengzhou
* Korea                 -Korea                 └─┬ Korea
** …                    --…                      └── …
/* ***************************************(long separator)****** */

Impact

Minimalist writing and brutal tutorials aims to deliver a all the value in as few words as possible. It therefor :

• define a guide of style for internal documentation
• shorten writing time for documentation
• eases creation of internal documentation
• eases maintenance and updates
• eases transmission and learning of know-how
• creates kick starters codes and instructions
• eases on-boarding of new teammates
• increase cross-training and team’s members know-how
• reduces human risk (see Bus factor)