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

T e c h n i c a l W r i t i n g f o r N o n - W r i t e r s F O S D E M r d B r u s s e l s , F e b r u a r y 3 2 0 1 8 T a n j a R o t h S U S E D o c u m e n t a t i o n T e a m T e c h n i c a l D o c u m e n t a t i o n S p e c i a l i s t t a r o t h @s u s e . c o m

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 o n s & A n s w e r s S o u r c e s

5 B a s i c R u l e s

# 1 : C h a n g e P e r s p e c t i v e “ D o n ' t t e l l m e h o w i t w o r k s . . . . . . t e l l m e h o w t o u s e i t ! ”

# 2 : O b e y t h e K I S S - P r i n c i p l e w o r d s “ u t i l i z e ” → “ u s e ” “ i n d i c a t e ” → “ s h o 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 o n s d i a l o g a p p e a r s . ” s e n t e n c e s o n e i d e a , o 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 o m p l e t e l y n e w ” , “ s i m p l y ”

# 3 : S p l i t I n t o C h u n k s c o m p l e x i n f o r m a t i o n s p l i t i n t o 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 o n e n e e d s t o k n o 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 o c e d u r e : < 1 0 s t e p s ) s t r u c t u r e d o e s i t r e f l e c t y o u r r e a d e r s ’ g o a l s ? f o r m f o l l o w s f u n c t i o n i n s t r u c t i o n s : a c t i v e v o i c e , p r o 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 o r e p r o c e d u r e / s t e p ● b a c k g r o u n d , c o n c e p t s : p r o c e d u r e b e f o r e ●

# 4 : B e C o n s i s t e n t c h o i c e o f w o r d s “symbolic link” – “softlink” – “symlink” s p e l l i n g “ a d d - o n ” – “ a d d o n ” – “ a d d o n ” p a r a l l e l c o n s t r u c t i o n s “Why white space is important: Attention focus ● It visually separates sections. ● Breaking content into chunks” ●

# 5 : A v o i d I n t e r r u p t i o n s l o n g c o m m a n d s , p a r t i c l e s “ h o w e v e r ” , “ n e v e r t h e l e s s ” , “ t h e r e f o r e ” , “ f o 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 o t , h o w e v e r , m a r k e d a s i n s t a l l e d . ” “ H o w e v e r , t h e y a r e n o 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 o w n . ” “ S h u t d o w n t h e s e r v e r . ”

Q & A S e s s i o n

S o 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 o n v e n t i o n s f o r W r i t e r s a n d E d i t o r s ” I S B N 9 7 8 - 0 - 1 3 - 2 1 0 1 3 0 - 1 ( 4 1 6 p . , 2 0 1 1 ) ● K o h l , J o h n R . “ T h e G l o 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 o c u m e n t a t i o n f o r a G l o 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 0 p . , 2 0 0 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 o p i n g Q u a l i t y T e c h n i c a l D o c u m e n t a t i o n : A H a n d b o o k f o r W r i t e s a n d E d i t o r s ” I S B N 9 7 8 - 0 1 3 1 4 7 7 4 9 0 ( 4 4 5 p . , 2 0 0 4 ) ● “ S U S E D o c u m e n t a t i o n S t y l e ” https://doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/ ● P https://unsplash.com h o t o s : a l l p h o t o s t a k e n f r o m ( u n d e r C C 0 )

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 o m m o n s A t t r i b u t i o n - S h a r e A l i k e 4 . 0 I n t e r n a t i o 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 o r a n y p u r p o s e ( e v e n c o m m e r c i a l l y ) a s l o n g a s A t t r i b u t i o 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 o 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 o u n d a t h t t p s : / / c r e a t i v e c o m m o n s . o r g / l i c e n s e s / b y - s a / 4 . 0 / G e n e r a l D i s c l a i m e r T h i s d o c u m e n t i s n o t t o b e c o n s t r u e d a s a p r o m i s e b y a n y p a r t i c i p a t i n g o r g a n i s a t i o n t o d e v e l o p , d e l i v e r , o r m a r k e t a p r o d u c t . I t i s n o t a c o m m i t m e n t t o d e l i v e r a n y m a t e r i a l , c o d e , o r f u n c t i o n a l i t y , a n d s h o u l d n o t b e r e l i e d u p o 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 o n s . o p e n S U S E m a k e s n o r e p r e s e n t a t i o n s o r w a r r a n t i e s w i t h r e s p e c t t o t h e c o n t e n t s o f t h i s d o 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 o r i m p l i e d w a r r a n t i e s o f m e r c h a n t a b i l i t y o r f i t n e s s f o r a n y p a r t i c u l a r p u r p o s e . T h e d e v e l o p m e n t , r e l e a s e , a n d t i m i n g o f f e a t u r e s o r f u n c t i o n a l i t y d e s c r i b e d f o r o p e n S U S E p r o d u c t s r e m a i n s a t t h e s o l e d i s c r e t i o n o f o p e n S U S E . F u r t h e r , o p e n S U S E r e s e r v e s t h e r i g h t t o r e v i s e t h i s d o c u m e n t a n d t o m a k e c h a n g e s t o i t s c o n t e n t , a t a n y t i m e , w i t h o u t o b l i g a t i o n t o n o t i f y a n y p e r s o n o r e n t i t y o f s u c h r e v i s i o n s o r c h a n g e s . A l l o 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 o n a r e t r a d e m a r k s o r r e g i s t e r e d t r a d e m a r k s o 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 o t h e r c o 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 o p e r t y o f t h e i r r e s p e c t i v e o 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 o w n r b r o w n @o p e n s u s e . o r g D e s i g n & I n s p i r a t i o n o p e n S U S E D e s i g n T e a m h t t p : / / o p e n s u s e . g i t h u b . i o / b r a n d i n g - g u i d e l i n e s /