Better Documentation
           …simple steps for greater impact!




   Sathya Srinivasan
   Technical Architect
   Conte...
“The value of documentation is only to be realized if the document
is well done. If it is poorly done, it will be worse th...
“In the beginner‟s mind there are
many possibilities. In the expert‟s
mind, there are few”
Shunryu Suzuki
Agenda


         Core principles

          Before-After

         Best practices
Perspective matters

                                     Fat
                                   content?
    Sugar! I wan...
Identify your readers
What do they need?
What do they need?




How much will they understand?
Know your readers

    Specify your target audience



    Provide context (background information)



    Specify scope...
It‟s taken all my life to
learn what not to play.
Dizzy Gillespie
Expand on content

    Level 0 : Summary



    Level 1 : High-level



    Level 2 : Detail





    Reference

Abstract or Summary

    For the casual reader or the

    executive
    Provides enough information to

    understand ...
High-level detail


    For the more involved

    reader or the manager

    Provides enough data

    points to conduc...
Full Detail

    For the involved reader

    Provides in-depth

    explanation of the high-level
    topics
Reference


            Give something for those
            interested in following up

                Related material
...
Add level of detail




      Level 0   Level 1   Level 2
How to make your points stick?

 Simplicity
 Unexpectedness
 Concreteness
 Credibility
 Emotion
 Story
“Our mission is to become the international leader in the space industry through
maximum team-centered innovation and stra...
“…put a man on the moon and return him
safely by the end of the decade.”
6 ways to see and 6 ways to show




                    Use the right picture to
                    convey your data
Use fonts and type to emphasize your
point


                 Si
    Contrast        ze

                 Weight
    Repet...
Constraints lead to
creativity
Agenda


         Core principles

          Before-After

         Best practices
Simplicity means the achievement of maximum
effect with minimum means.
Dr. Koichi Kawana
Darth Vader…



    …or…


Yoda?
Microsoft…




…or…
       Apple?
How to create captivating graphics
How to create captivating graphics
How to create a good-looking front page


                        alignment
                                     contrast
...
How to strengthen your resume
Your message is important – don’t drown it
Pick the right graphic to express your data
Best Practices




      Core principles

       Before-After

      Best practices
Common Best Practices
    Provide visual equivalents where applicable





    DO NOT USE ALL-CAPS – It reduces readabili...
Best Practices : Document

                   Do not separate content from heading
               


                   M...
Correct document properties
Include your name and company name
… not your someone else’s!
Correct your reds, greens, and blues
         – Spelling errors
 Red
 Green – Grammatical errors
         – Contextual e...
Do not leave empty rows in tables
You can always hit the TAB button later!
Use format and styling
Identify headings and normal text
Use them for generating TOC
Best Practices : Presentation
    Pictures + Text = Better presentation


    Use animation only when needed (such as add...
Apply corporate theme




… even if it is a one-off deck
Apply slide style on copy/paste
Best Practices : Spreadsheet
    Avoid using macros when possible



    Remove unwanted sheets (Sheet2, Sheet3)



    ...
Distinguish the header
Wrap text in cells
Make spreadsheets printer-friendly

    Repeat headers


    Set orientation


    Adjust page breaks


    Add cell bo...
Adjust your columns
Best Practices : E-mail
    Use Spelling & Grammar check before hitting „send‟



    Read what you wrote at least once
...
“First you master your instrument.
Then you master the music. Then
you forget about all the shit you just
learned and just...
Don‟t have the time?
References
Hyperlinks

    http://www.garrreynolds.com

    http://www.presentationzen.com

    http://www.beyondbulletpoints.com
...
Better Documentation
Better Documentation
Better Documentation
Upcoming SlideShare
Loading in …5
×

Better Documentation

1,264 views

Published on

Much as we crib about Microsoft Office products, it's the most used software suite in almost any industry. However, it's also the one that people spend no official time learning. This presentation shows how simple design concepts applied to Microsoft Office products can greatly improve the quality of your documents and make it pleasurable for the reader.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,264
On SlideShare
0
From Embeds
0
Number of Embeds
181
Actions
Shares
0
Downloads
68
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Better Documentation

  1. 1. Better Documentation …simple steps for greater impact! Sathya Srinivasan Technical Architect Content & Portal Solutions
  2. 2. “The value of documentation is only to be realized if the document is well done. If it is poorly done, it will be worse than no document at all.” Gerald M Weinberg
  3. 3. “In the beginner‟s mind there are many possibilities. In the expert‟s mind, there are few” Shunryu Suzuki
  4. 4. Agenda Core principles Before-After Best practices
  5. 5. Perspective matters Fat content? Sugar! I want Calories? it! mmm… cookie…
  6. 6. Identify your readers
  7. 7. What do they need?
  8. 8. What do they need? How much will they understand?
  9. 9. Know your readers Specify your target audience  Provide context (background information)  Specify scope  Do not assume reader‟s background beyond minimum  Provide future references 
  10. 10. It‟s taken all my life to learn what not to play. Dizzy Gillespie
  11. 11. Expand on content Level 0 : Summary  Level 1 : High-level  Level 2 : Detail  Reference 
  12. 12. Abstract or Summary For the casual reader or the  executive Provides enough information to  understand the purpose and what the document achieves
  13. 13. High-level detail For the more involved  reader or the manager Provides enough data  points to conduct meetings or conversations
  14. 14. Full Detail For the involved reader  Provides in-depth  explanation of the high-level topics
  15. 15. Reference Give something for those interested in following up Related material  Documentation supporting  claims made in text
  16. 16. Add level of detail Level 0 Level 1 Level 2
  17. 17. How to make your points stick?  Simplicity  Unexpectedness  Concreteness  Credibility  Emotion  Story
  18. 18. “Our mission is to become the international leader in the space industry through maximum team-centered innovation and strategically targeted aerospace initiatives.”
  19. 19. “…put a man on the moon and return him safely by the end of the decade.”
  20. 20. 6 ways to see and 6 ways to show Use the right picture to convey your data
  21. 21. Use fonts and type to emphasize your point Si Contrast ze Weight Repetition Structure Alignment Form Proximity Direction color
  22. 22. Constraints lead to creativity
  23. 23. Agenda Core principles Before-After Best practices
  24. 24. Simplicity means the achievement of maximum effect with minimum means. Dr. Koichi Kawana
  25. 25. Darth Vader… …or… Yoda?
  26. 26. Microsoft… …or… Apple?
  27. 27. How to create captivating graphics
  28. 28. How to create captivating graphics
  29. 29. How to create a good-looking front page alignment contrast repetition proximity
  30. 30. How to strengthen your resume
  31. 31. Your message is important – don’t drown it
  32. 32. Pick the right graphic to express your data
  33. 33. Best Practices Core principles Before-After Best practices
  34. 34. Common Best Practices Provide visual equivalents where applicable  DO NOT USE ALL-CAPS – It reduces readability  And how about this very important CAN YOU READ THIS BIG BLOB Or can you read this equally big blob piece of information contained in OF TEXT SCREAMING AT YOU of text that contains equally important BUT NEVERTHELESS CONTAINS information without screaming? this big blob of text with appropriate VERY IMPORTANT emphasis and white space? INFORMATION? Use Only Initial Caps When Necessary – It‟s distracting  …or important information about Big Important Information About Big Company with initial caps for nouns Company But With All Initial Caps… only? Keep consistent fonts 
  35. 35. Best Practices : Document Do not separate content from heading  Make your documents printer-friendly  Apply the corporate template to the  document even if it is internal or one- off and… 
  36. 36. Correct document properties Include your name and company name … not your someone else’s!
  37. 37. Correct your reds, greens, and blues – Spelling errors  Red  Green – Grammatical errors – Contextual errors (new in 2007)  Blue
  38. 38. Do not leave empty rows in tables You can always hit the TAB button later!
  39. 39. Use format and styling Identify headings and normal text Use them for generating TOC
  40. 40. Best Practices : Presentation Pictures + Text = Better presentation  Use animation only when needed (such as adding suspense)  Presentation = Slides [+ Notes + Handout]  Reduce the footprint of the document  Remove empty bullets  and… 
  41. 41. Apply corporate theme … even if it is a one-off deck
  42. 42. Apply slide style on copy/paste
  43. 43. Best Practices : Spreadsheet Avoid using macros when possible  Remove unwanted sheets (Sheet2, Sheet3)  Rename sheets to reflect the associated content  and… 
  44. 44. Distinguish the header
  45. 45. Wrap text in cells
  46. 46. Make spreadsheets printer-friendly Repeat headers  Set orientation  Adjust page breaks  Add cell borders  Add header/footer info 
  47. 47. Adjust your columns
  48. 48. Best Practices : E-mail Use Spelling & Grammar check before hitting „send‟  Read what you wrote at least once  Add your contact information – always!  Do not cut and paste images – insert them as JPEG attachments 
  49. 49. “First you master your instrument. Then you master the music. Then you forget about all the shit you just learned and just play” Charlie Parker
  50. 50. Don‟t have the time?
  51. 51. References
  52. 52. Hyperlinks http://www.garrreynolds.com  http://www.presentationzen.com  http://www.beyondbulletpoints.com  http://www.istockphoto.com  http://www.dreamstime.com 

×