[PPT] - T e c h n i c a l W r i t i n g f o r N o n - PowerPoint Presentation

SLIDE 1

T a n j a R

t

h

S U S E D

c

u m e n t a t i

n

T e a m T e c h n i c a l D

c

u m e n t a t i

n

S p e c i a l i s t t a r

t

h @s u s e . c

m

T e c h n i c a l W r i t i n g f

r

N

n
W

r i t e r s

F O S D E M B r u s s e l s , F e b r u a r y 3

r d

2 1 8

SLIDE 2

O v e r v i e w

W a r m

u

p 5 B a s i c R u l e s Q u e s t i

n

s & A n s w e r s S

u

r c e s

SLIDE 3

5 B a s i c R u l e s

SLIDE 4

# 1 : C h a n g e P e r s p e c t i v e

. . . t e l l m e h

w

t

u

s e i t ! ” “ D

n

' t t e l l m e h

w

i t w

r

k s . . .

SLIDE 5

# 2 : O b e y t h e K I S S

P

r i n c i p l e

w

r

d s

“ u t i l i z e ” → “ u s e ” “ i n d i c a t e ” → “ s h

w

” , “ t e l l ” , “ s a y ” “ p r e r e q u i s i t e ” → “ r e q u i r e m e n t ”

g r a m m a r

“ C l i c k O K . T h e P r i n t e r O p t i

n

s d i a l

g

a p p e a r s . ”

s e n t e n c e s

n

e i d e a ,

n

e s e n t e n c e

f i l l e r s

“ a l r e a d y e x i s t i n g ” , “ c

m

p l e t e l y n e w ” , “ s i m p l y ”

SLIDE 6

# 3 : S p l i t I n t

C

h u n k s

c

m

p l e x i n f

r

m a t i

n

s p l i t i n t

c

h u n k s f i r s t t h i n g s f i r s t : w h a t e v e r y

n

e n e e d s t

k

n

w

3

l

e v e l h i e r a r c h y : 1 . – 1 . 1 – 1 . 1 . 1 M i l l e r ’ s L a w : 7 ± 2 i t e m s ( p r

c

e d u r e : < 1 s t e p s )

s t r u c t u r e

d

e

s i t r e f l e c t y

u

r r e a d e r s ’ g

a

l s ? f

r

m f

l

l

w

s f u n c t i

n
i

n s t r u c t i

n

s : a c t i v e v

i

c e , p r

c

e d u r e w i t h s t e p s

w

a r n i n g : b e f

r

e p r

c

e d u r e / s t e p

b

a c k g r

u

n d , c

n

c e p t s : b e f

r

e p r

c

e d u r e

SLIDE 7

# 4 : B e C

n

s i s t e n t

c h

i

c e

f

w

r

d s

“symbolic link” – “softlink” – “symlink”

s p e l l i n g

“ a d d

n

” – “ a d d

n

” – “ a d d

n

”

p a r a l l e l c

n

s t r u c t i

n

s

“Why white space is important:

Attention focus
It visually separates sections.
Breaking content into chunks”

SLIDE 8

# 5 : A v

i

d I n t e r r u p t i

n

s

l

n

g c

m

m a n d s , p a r t i c l e s

“ h

w

e v e r ” , “ n e v e r t h e l e s s ” , “ t h e r e f

r

e ” , “ f

r

e x a m p l e ” , “ i f n e c e s s a r y ” …

“ T h e y a r e n

t

, h

w

e v e r , m a r k e d a s i n s t a l l e d . ” “ H

w

e v e r , t h e y a r e n

t

m a r k e d a s i n s t a l l e d . ”

p h r a s a l v e r b s

“ S h u t t h e s e r v e r d

w

n . ” “ S h u t d

w

n t h e s e r v e r . ”

SLIDE 9

Q & A S e s s i

n

SLIDE 10

S

u

r c e s

Comprehensive list of sources: https://git.io/fosdem-tw-src

D

e R e s p i n i s , F r a n c i s e t a l . “ T h e I B M S t y l e G u i d e : C

n

v e n t i

n

s f

r

W r i t e r s a n d E d i t

r

s ” I S B N 9 7 8

1

3

2

1 1 3

1

( 4 1 6 p . , 2 1 1 )

K
h

l , J

h

n R . “ T h e G l

b

a l E n g l i s h S t y l e G u i d e : W r i t i n g C l e a r , T r a n s l a t a b l e D

c

u m e n t a t i

n

f

r

a G l

b

a l M a r k e t ” I S B N 9 7 8

1
5

9 9 9 4

6

5 7

3

( 3 1 p . , 2 8 )

Achtelig, Marc

“How to Write That F***ing Manual: Ohne Umschweife zu benutzerfreundlichen Handbüchern und Hilfen” Bilingual edition: English + German ISBN 978-3-943860-01-6 (256 p., 2012)

H

a r g i s , G r e t c h e n e t a l . “ D e v e l

p

i n g Q u a l i t y T e c h n i c a l D

c

u m e n t a t i

n

: A H a n d b

k

f

r

W r i t e s a n d E d i t

r

s ” I S B N 9 7 8

1

3 1 4 7 7 4 9 ( 4 4 5 p . , 2 4 )

“

S U S E D

c

u m e n t a t i

n

S t y l e ” https://doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/

P

h

t
s

: a l l p h

t
s

t a k e n f r

m

https://unsplash.com ( u n d e r C C )

SLIDE 11

L i c e n s e

T h i s s l i d e d e c k i s l i c e n s e d u n d e r t h e C r e a t i v e C

m

m

n

s A t t r i b u t i

n
S

h a r e A l i k e 4 . I n t e r n a t i

n

a l l i c e n s e . I t c a n b e s h a r e d a n d a d a p t e d f

r

a n y p u r p

s

e ( e v e n c

m

m e r c i a l l y ) a s l

n

g a s A t t r i b u t i

n

i s g i v e n a n d a n y d e r i v a t i v e w

r

k i s d i s t r i b u t e d u n d e r t h e s a m e l i c e n s e . D e t a i l s c a n b e f

u

n d a t h t t p s : / / c r e a t i v e c

m

m

n

s .

r

g / l i c e n s e s / b y

s

a / 4 . /

G e n e r a l D i s c l a i m e r

T h i s d

c

u m e n t i s n

t

t

b

e c

n

s t r u e d a s a p r

m

i s e b y a n y p a r t i c i p a t i n g

r

g a n i s a t i

n

t

d

e v e l

p

, d e l i v e r ,

r

m a r k e t a p r

d

u c t . I t i s n

t

a c

m

m i t m e n t t

d

e l i v e r a n y m a t e r i a l , c

d

e ,

r

f u n c t i

n

a l i t y , a n d s h

u

l d n

t

b e r e l i e d u p

n

i n m a k i n g p u r c h a s i n g d e c i s i

n

s .

p

e n S U S E m a k e s n

r

e p r e s e n t a t i

n

s

r

w a r r a n t i e s w i t h r e s p e c t t

t

h e c

n

t e n t s

f

t h i s d

c

u m e n t , a n d s p e c i f i c a l l y d i s c l a i m s a n y e x p r e s s

r

i m p l i e d w a r r a n t i e s

f

m e r c h a n t a b i l i t y

r

f i t n e s s f

r

a n y p a r t i c u l a r p u r p

s

e . T h e d e v e l

p

m e n t , r e l e a s e , a n d t i m i n g

f

f e a t u r e s

r

f u n c t i

n

a l i t y d e s c r i b e d f

r
p

e n S U S E p r

d

u c t s r e m a i n s a t t h e s

l

e d i s c r e t i

n
f
p

e n S U S E . F u r t h e r ,

p

e n S U S E r e s e r v e s t h e r i g h t t

r

e v i s e t h i s d

c

u m e n t a n d t

m

a k e c h a n g e s t

i

t s c

n

t e n t , a t a n y t i m e , w i t h

u

t

b

l i g a t i

n

t

n
t

i f y a n y p e r s

n
r

e n t i t y

f

s u c h r e v i s i

n

s

r

c h a n g e s . A l l

p

e n S U S E m a r k s r e f e r e n c e d i n t h i s p r e s e n t a t i

n

a r e t r a d e m a r k s

r

r e g i s t e r e d t r a d e m a r k s

f

S U S E L L C , i n t h e U n i t e d S t a t e s a n d

t

h e r c

u

n t r i e s . A l l t h i r d

p

a r t y t r a d e m a r k s a r e t h e p r

p

e r t y

f

t h e i r r e s p e c t i v e

w

n e r s .

C r e d i t s

T e m p l a t e R i c h a r d B r

w

n r b r

w

n @o p e n s u s e .

r

g D e s i g n & I n s p i r a t i

n
p

e n S U S E D e s i g n T e a m h t t p : / /

p

e n s u s e . g i t h u b . i

/

b r a n d i n g

g

u i d e l i n e s /