Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documentation is UX

Glenn
April 22, 2023

Documentation is UX

We spend a lot of time designing beautiful websites and tools; Crafting the perfect onboarding experiences for our users. Obsessing over colours and buttons and fonts, and yet ... why is writing the user documentation always left to last? and why is it always so difficult? and why does it not spark joy in our users?

This talk will look at the importance of documentation for your web based and CLI tools (because it'll be the first thing they go looking for when something goes wrong!) and will give tips on how to create the three types (and many forms) of product documentation so that users will truly enjoy the UX you created for them.

Glenn

April 22, 2023
Tweet

More Decks by Glenn

Other Decks in Technology

Transcript

  1. @glennsarti glenn-sarti
    Glenn Sarti - Senior Software Engineer at

    View Slide

  2. According to Nielsen Norman Group, 'user
    experience' includes all the aspects of the interaction
    between the end-user with the company, its services,
    and its products.
    @glennsarti
    - https://en.wikipedia.org/wiki/User_experience

    View Slide

  3. … According to the ISO definition, user experience includes
    all the users' emotions, beliefs, preferences, perceptions, physical
    and psychological responses, behaviors and accomplishments
    that occur before, during, and after use …
    @glennsarti
    - https://en.wikipedia.org/wiki/User_experience

    View Slide

  4. @glennsarti
    - https://en.wikipedia.org/wiki/User_experience
    … According to the ISO definition, user experience includes
    all the users' emotions, beliefs, preferences, perceptions, physical
    and psychological responses, behaviors and accomplishments
    that occur before, during, and after use …

    View Slide

  5. View Slide

  6. @glennsarti

    View Slide

  7. View Slide

  8. @glennsarti

    View Slide

  9. @glennsarti

    View Slide

  10. @glennsarti

    View Slide

  11. @glennsarti
    Icons Colour

    View Slide

  12. @glennsarti
    CLI Applications

    View Slide

  13. @glennsarti

    View Slide

  14. @glennsarti

    View Slide

  15. @glennsarti
    /? -h --help
    help –H ? …

    View Slide

  16. @glennsarti
    > kubectl get pod example-pod1

    View Slide

  17. @glennsarti
    > docker plugin create [OPTIONS]

    View Slide

  18. @glennsarti
    > docker start my_container

    View Slide

  19. @glennsarti
    > docker ps
    > docker rm
    > docker top

    View Slide

  20. @glennsarti
    > docker rmi my_image

    View Slide

  21. @glennsarti
    > docker plugin create [OPTIONS]
    > docker start my_container
    > docker ps
    > docker rm
    > docker top
    > docker rmi my_image

    View Slide

  22. @glennsarti
    Aside : Metaphors

    View Slide

  23. @glennsarti
    Aside : Metaphors
    - https://www.youtube.com/watch?v=rQxJefYGWwU&t=346s

    View Slide

  24. @glennsarti
    - https://www.youtube.com/watch?v=rQxJefYGWwU&t=346s
    As a consequence of our brains reaching for metaphors to
    come to grips with the world around us, we gain partial
    understanding of experiences. And which parts we grasp versus
    which parts elude us are determined by the metaphors we use.

    View Slide

  25. @glennsarti
    - https://www.youtube.com/watch?v=rQxJefYGWwU&t=346s
    As a consequence of our brains reaching for metaphors to
    come to grips with the world around us, we gain partial
    understanding of experiences. And which parts we grasp versus
    which parts elude us are determined by the metaphors we use.

    View Slide

  26. @glennsarti
    Where’s the docs?

    View Slide

  27. @glennsarti
    Where’s the docs?

    View Slide

  28. @glennsarti

    View Slide

  29. @glennsarti

    View Slide

  30. @glennsarti

    View Slide

  31. @glennsarti

    View Slide

  32. @glennsarti
    First use
    Where’s the docs?

    View Slide

  33. @glennsarti
    First use
    Failures
    Where’s the docs?

    View Slide

  34. @glennsarti

    View Slide

  35. @glennsarti
    🔊 🔊
    🔊 🔊
    🔊 🔊
    🔊 🔊

    View Slide

  36. @glennsarti
    First use
    Failures
    Where’s the docs?

    View Slide

  37. @glennsarti

    View Slide

  38. @glennsarti
    Service Manual Install manual

    View Slide

  39. @glennsarti
    First use
    Failures
    Modifications
    Where’s the docs?

    View Slide

  40. @glennsarti
    First use
    Failures
    Modifications
    UX, Pwsh and Docs

    View Slide

  41. @glennsarti
    PS> Import-Module bad_module
    WARNING: The names of some imported commands from the module
    'bad_module' include unapproved verbs that might make them less
    discoverable. To find the commands with unapproved verbs, run the
    Import-Module command again with the Verbose parameter. For a list
    of approved verbs, type Get-Verb.
    UX, Pwsh and Docs

    View Slide

  42. @glennsarti
    Get-Help
    UX, Pwsh and Docs

    View Slide

  43. @glennsarti
    UX, Pwsh and Docs

    View Slide

  44. @glennsarti
    UX, Pwsh and Docs

    View Slide

  45. @glennsarti
    UX, Pwsh and Docs

    View Slide

  46. @glennsarti
    First use
    Failures
    Modifications
    UX, Pwsh and Docs

    View Slide

  47. @glennsarti
    PS> Import-Module bad_module
    WARNING: The names of some imported commands from the module
    'bad_module' include unapproved verbs that might make them less
    discoverable. To find the commands with unapproved verbs, run the
    Import-Module command again with the Verbose parameter. For a list
    of approved verbs, type Get-Verb.
    UX, Pwsh and Docs

    View Slide

  48. @glennsarti
    PS> Import-Module bad_module
    WARNING: The names of some imported commands from the module
    'bad_module' include unapproved verbs that might make them less
    discoverable. To find the commands with unapproved verbs, run the
    Import-Module command again with the Verbose parameter. For a list
    of approved verbs, type Get-Verb.
    UX, Pwsh and Docs

    View Slide

  49. @glennsarti
    PS> Import-Module bad_module
    WARNING: The names of some imported commands from the module
    'bad_module' include unapproved verbs that might make them less
    discoverable. To find the commands with unapproved verbs, run the
    Import-Module command again with the Verbose parameter. For a list
    of approved verbs, type Get-Verb.
    UX, Pwsh and Docs

    View Slide

  50. @glennsarti
    First use
    Failures
    Modifications
    UX, Pwsh and Docs

    View Slide

  51. @glennsarti
    UX, Pwsh and Docs

    View Slide

  52. @glennsarti
    UX, Pwsh and Docs

    View Slide

  53. @glennsarti
    UX, Pwsh and Docs
    PS> Get-Help Get-AzResourceGroupDeploymentWhatIfResult -Detailed
    NAME
    Get-AzResourceGroupDeploymentWhatIfResult
    SYNOPSIS
    Gets a template What-If result for a deployment at resource group scope.
    SYNTAX
    Get-AzResourceGroupDeploymentWhatIfResult [-DefaultProfile
    ] [-ExcludeChangeType ] [-Mode
    {Incremental | Complete}] [-Name ] [-Pre] -ResourceGroupName [-ResultFormat {ResourceIdOnly | FullResourcePayloads}]
    [-SkipTemplateParameterPrompt] -TemplateFile []
    Get-AzResourceGroupDeploymentWhatIfResult [-DefaultProfile
    ] [-ExcludeChangeType ] [-Mode
    {Incremental | Complete}] [-Name ] [-Pre] -ResourceGroupName [-ResultFormat {ResourceIdOnly | FullResourcePayloads}]
    [-SkipTemplateParameterPrompt] -TemplateFile -TemplateParameterObject []
    Get-AzResourceGroupDeploymentWhatIfResult [-DefaultProfile
    ] [-ExcludeChangeType ] [-Mode
    {Incremental | Complete}] [-Name ] [-Pre] -ResourceGroupName [-ResultFormat {ResourceIdOnly | FullResourcePayloads}]
    [-SkipTemplateParameterPrompt] -TemplateFile -TemplateParameterFile []
    Get-AzResourceGroupDeploymentWhatIfResult [-DefaultProfile
    ] [-ExcludeChangeType ] [-Mode
    {Incremental | Complete}] [-Name ] [-Pre] -ResourceGroupName [-ResultFormat {ResourceIdOnly | FullResourcePayloads}]
    [-SkipTemplateParameterPrompt] -TemplateUri []
    ... So much scrolling later ... 🥱

    View Slide

  54. @glennsarti
    UX, Pwsh and Docs

    View Slide

  55. @glennsarti
    Documentation
    is part of the UX.

    View Slide

  56. @glennsarti
    Documentation
    is part of the UX.

    View Slide

  57. @glennsarti
    - https://www.powershellgallery.com/packages/platyPS

    View Slide

  58. @glennsarti
    What & Who

    View Slide

  59. @glennsarti
    Can they use the module Everyone
    Learn something general about the module
    First time users
    Returning inexperienced users
    Experienced PowerShell users
    Perform a specific task with the module Experienced PowerShell users
    Find why an error happened Returning inexperienced users
    Submit a bug report Returning inexperienced users
    Experienced PowerShell users
    What Who

    View Slide

  60. @glennsarti
    Can they use the module Everyone
    Learn something general about the module
    First time users
    Returning inexperienced users
    Experienced PowerShell users
    Perform a specific task with the module Experienced PowerShell users
    Find why an error happened Returning inexperienced users
    Submit a bug report Returning inexperienced users
    Experienced PowerShell users
    What Who

    View Slide

  61. @glennsarti
    Can they use the module Everyone
    Learn something general about the module
    First time users
    Returning inexperienced users
    Experienced PowerShell users
    Perform a specific task with the module Experienced PowerShell users
    Find why an error happened Returning inexperienced users
    Submit a bug report Returning inexperienced users
    Experienced PowerShell users
    What Who

    View Slide

  62. @glennsarti
    Can they use the module Everyone
    Learn something general about the module
    First time users
    Returning inexperienced users
    Experienced PowerShell users
    Perform a specific task with the module Experienced PowerShell users
    Find why an error happened Returning inexperienced users
    Submit a bug report Returning inexperienced users
    Experienced PowerShell users
    What Who

    View Slide

  63. @glennsarti
    User Stories
    As a user who has never seen the PlayPS module before
    I would like to quickly find the module requirements
    so that I can figure out if I can use the module on my computer

    View Slide

  64. @glennsarti
    User Personas
    Name: Harper
    PowerShell skill: Basic
    Job Role: IT Support
    PS Version: 5.1
    OS: Windows
    PC Type: Desktop
    Name: Riley
    PowerShell skill: Medium
    Job Role: QA Lead
    PS Version: 7.3
    OS: OSX
    PC Type: Laptop

    View Slide

  65. @glennsarti
    User Journeys
    … journey mapping starts by compiling
    a series of user actions into a timeline
    … with user thoughts and emotions in
    order to create a narrative … ultimately
    leading to a visualization.
    - https://www.nngroup.com/articles/journey-mapping-101/

    View Slide

  66. @glennsarti
    Can they use the module Everyone
    Learn something general about the module
    First time users
    Returning inexperienced users
    Experienced PowerShell users
    Perform a specific task with the module Experienced PowerShell users
    Find why an error happened Returning inexperienced users
    Submit a bug report Returning inexperienced users
    Experienced PowerShell users
    What Who

    View Slide

  67. @glennsarti
    Types of Documentation

    View Slide

  68. @glennsarti
    Types of Documentation
    - https://www.youtube.com/watch?v=0S0eAuGzjpI

    View Slide

  69. @glennsarti
    Reference Documentation
    Explains technical details
    Mostly ubiquitous
    Unforgivable if missing
    Insufficient

    View Slide

  70. @glennsarti
    Conceptual Documentation
    Least common type
    Mandatory for good UX
    Answers a specific question

    View Slide

  71. @glennsarti
    Narrative Documentation
    Explains how and why a user can do a thing
    Uses the structure of a story
    Most effective type
    Diggers of the pit of success

    View Slide

  72. @glennsarti
    Types of Documentation
    Reference
    Get-Help Get-HelpPreview
    Get-Help … –Online
    PowerShell Gallery
    Get-Help platyps

    View Slide

  73. @glennsarti
    Types of Documentation
    Reference
    Get-Help Get-HelpPreview
    Get-Help … –Online
    PowerShell Gallery
    Get-Help platyps
    Conceptual Source Repository
    README
    Get-Help about_Functions

    View Slide

  74. @glennsarti
    Types of Documentation
    Reference
    Get-Help Get-HelpPreview
    Get-Help … –Online
    PowerShell Gallery
    Get-Help platyps
    Conceptual Source Repository
    README
    Get-Help about_Functions
    Narrative README
    PowerShell Gallery
    External sites (Blogs etc.)

    View Slide

  75. @glennsarti
    - https://docsfordevelopers.com
    Most of us have to learn the
    importance of documentation
    the hard way, by finding it
    missing when we need it the
    most.

    View Slide

  76. @glennsarti
    Reference
    Conceptual
    Procedural
    Types of Documentation
    Getting Started
    READMEs
    Code Comments

    View Slide

  77. @glennsarti
    Reference
    Conceptual
    Procedural
    Types of Documentation
    Getting Started
    READMEs
    Code Comments

    View Slide

  78. @glennsarti
    Reference
    Conceptual
    Procedural
    Types of Documentation
    Getting Started
    READMEs
    Code Comments

    View Slide

  79. @glennsarti
    Reference
    Conceptual
    Procedural
    Types of Documentation
    Getting Started
    READMEs
    Code Comments

    View Slide

  80. @glennsarti
    Can they use the module Everyone
    Learn something general about the module
    First time users
    Returning inexperienced users
    Experienced PowerShell users
    Perform a specific task with the module Experienced PowerShell users
    Find why an error happened Returning inexperienced users
    Submit a bug report Returning inexperienced users
    Experienced PowerShell users
    What Who

    View Slide

  81. @glennsarti
    Can they use the module Everyone
    Learn something general about the module
    First time users
    Returning inexperienced users
    Experienced PowerShell users
    Perform a specific task with the module Experienced PowerShell users
    Find why an error happened Returning inexperienced users
    Submit a bug report Returning inexperienced users
    Experienced PowerShell users
    Run tests New Contributor
    What Who

    View Slide

  82. @glennsarti

    View Slide

  83. @glennsarti
    From Where
    Chat
    Email
    “Knowledge Bases”
    Forums
    Issue Trackers
    Meta-documents

    View Slide

  84. @glennsarti
    From Where
    Chat
    Email
    “Knowledge Bases”
    Forums
    Issue Trackers
    Meta-documents

    View Slide

  85. @glennsarti
    From Where
    Chat
    Email
    “Knowledge Bases”
    Forums
    Issue Trackers
    Meta-documents
    Asking Humans

    View Slide

  86. @glennsarti
    To where?

    View Slide

  87. @glennsarti
    Findable
    Readable
    Changeable

    View Slide

  88. @glennsarti
    Demo

    View Slide

  89. @glennsarti
    Demo
    https://sarti.dev/platyPS

    View Slide

  90. @glennsarti
    Documentarian
    https://github.com/microsoft/Documentarian
    - https://sarti.dev/platyPS

    View Slide

  91. @glennsarti
    - https://sarti.dev/platyPS

    View Slide

  92. @glennsarti

    View Slide

  93. @glennsarti

    View Slide

  94. @glennsarti

    View Slide

  95. @glennsarti

    View Slide

  96. @glennsarti

    View Slide

  97. @glennsarti

    View Slide

  98. @glennsarti

    View Slide

  99. @glennsarti
    Can they use the module Everyone
    Learn something general about the module
    First time users
    Returning inexperienced users
    Experienced PowerShell users
    Perform a specific task with the module Experienced PowerShell users
    Find why an error happened Returning inexperienced users
    Submit a bug report Returning inexperienced users
    Experienced PowerShell users
    Run tests New Contributor
    What Who






    View Slide

  100. @glennsarti
    Source Module
    PlatyPS
    Generation
    docsy-pwsh
    Static
    documentation hugo
    GitHub
    Pages
    GitHub Actions
    - https://github.com/glennsarti/platyPS/blob/gs/docs-demo/.github/workflows/publish_docs.yaml

    View Slide

  101. @glennsarti

    View Slide

  102. @glennsarti

    View Slide

  103. @glennsarti
    Demo
    https://sarti.dev/platyPS

    View Slide

  104. @glennsarti

    View Slide

  105. @glennsarti
    http://sarti.dev/platyPS
    https://speakerdeck.com/glennsarti
    https://powershellsummit.org/sessionfeedback
    THANK YOU!
    Please use the link below to submit a session rating!

    View Slide

  106. @glennsarti
    Resources
    Source Code
    https://github.com/glennsarti/platyPS
    https://www.powershellgallery.com/packages/platyPS
    User Experience
    https://en.wikipedia.org/wiki/User_experience
    Eric Sorenson - Metaphors
    https://www.youtube.com/watch?v=rQxJefYGWwU&t=346s
    Journey Mapping
    https://www.nngroup.com/articles/journey-mapping-101/
    Images
    https://unsplash.com
    @glennsarti

    View Slide

  107. @glennsarti
    Resources
    Documentation as UX
    https://www.youtube.com/watch?v=0S0eAuGzjpI
    Docs for Developers
    https://docsfordevelopers.com
    @glennsarti

    View Slide