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.

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