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
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 “
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 “
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 … “
6. @glennsarti
8. @glennsarti
9. @glennsarti
10. @glennsarti
11. @glennsarti Icons Colour
12. @glennsarti CLI Applications
13. @glennsarti
14. @glennsarti
15. @glennsarti /? -h --help help –H ? …
16. @glennsarti > kubectl get pod example-pod1
17. @glennsarti > docker plugin create [OPTIONS]
18. @glennsarti > docker start my_container
19. @glennsarti > docker ps > docker rm > docker top
20. @glennsarti > docker rmi my_image
21. @glennsarti > docker plugin create [OPTIONS] > docker start my_container > docker ps > docker rm > docker top > docker rmi my_image
22. @glennsarti Aside : Metaphors
23. @glennsarti Aside : Metaphors - https://www.youtube.com/watch?v=rQxJefYGWwU&t=346s
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. “
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. “
26. @glennsarti Where’s the docs?
27. @glennsarti Where’s the docs?
28. @glennsarti
29. @glennsarti
30. @glennsarti
31. @glennsarti
32. @glennsarti First use Where’s the docs?
33. @glennsarti First use Failures Where’s the docs?
34. @glennsarti
35. @glennsarti 🔊 🔊 🔊 🔊 🔊 🔊 🔊 🔊
36. @glennsarti First use Failures Where’s the docs?
37. @glennsarti
38. @glennsarti Service Manual Install manual
39. @glennsarti First use Failures Modifications Where’s the docs?
40. @glennsarti First use Failures Modifications UX, Pwsh and Docs
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
42. @glennsarti Get-Help UX, Pwsh and Docs
43. @glennsarti UX, Pwsh and Docs
44. @glennsarti UX, Pwsh and Docs
45. @glennsarti UX, Pwsh and Docs
46. @glennsarti First use Failures Modifications UX, Pwsh and Docs
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
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
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
50. @glennsarti First use Failures Modifications UX, Pwsh and Docs
51. @glennsarti UX, Pwsh and Docs
52. @glennsarti UX, Pwsh and Docs
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 <Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer>] [-ExcludeChangeType <System.String[]>] [-Mode {Incremental | Complete}] [-Name <System.String>] [-Pre] -ResourceGroupName <System.String> [-ResultFormat {ResourceIdOnly | FullResourcePayloads}] [-SkipTemplateParameterPrompt] -TemplateFile <System.String> [<CommonParameters>] Get-AzResourceGroupDeploymentWhatIfResult [-DefaultProfile <Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer>] [-ExcludeChangeType <System.String[]>] [-Mode {Incremental | Complete}] [-Name <System.String>] [-Pre] -ResourceGroupName <System.String> [-ResultFormat {ResourceIdOnly | FullResourcePayloads}] [-SkipTemplateParameterPrompt] -TemplateFile <System.String> -TemplateParameterObject <System.Collections.Hashtable> [<CommonParameters>] Get-AzResourceGroupDeploymentWhatIfResult [-DefaultProfile <Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer>] [-ExcludeChangeType <System.String[]>] [-Mode {Incremental | Complete}] [-Name <System.String>] [-Pre] -ResourceGroupName <System.String> [-ResultFormat {ResourceIdOnly | FullResourcePayloads}] [-SkipTemplateParameterPrompt] -TemplateFile <System.String> -TemplateParameterFile <System.String> [<CommonParameters>] Get-AzResourceGroupDeploymentWhatIfResult [-DefaultProfile <Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer>] [-ExcludeChangeType <System.String[]>] [-Mode {Incremental | Complete}] [-Name <System.String>] [-Pre] -ResourceGroupName <System.String> [-ResultFormat {ResourceIdOnly | FullResourcePayloads}] [-SkipTemplateParameterPrompt] -TemplateUri <System.String> [<CommonParameters>] ... So much scrolling later ... 🥱
54. @glennsarti UX, Pwsh and Docs
55. @glennsarti Documentation is part of the UX.
56. @glennsarti Documentation is part of the UX.
57. @glennsarti - https://www.powershellgallery.com/packages/platyPS
58. @glennsarti What & Who
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
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
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
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
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
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
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/
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
67. @glennsarti Types of Documentation
68. @glennsarti Types of Documentation - https://www.youtube.com/watch?v=0S0eAuGzjpI
69. @glennsarti Reference Documentation Explains technical details Mostly ubiquitous Unforgivable if missing Insufficient
70. @glennsarti Conceptual Documentation Least common type Mandatory for good UX Answers a specific question
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
72. @glennsarti Types of Documentation Reference Get-Help Get-HelpPreview Get-Help … –Online PowerShell Gallery Get-Help platyps
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
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.)
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. “
76. @glennsarti Reference Conceptual Procedural Types of Documentation Getting Started READMEs Code Comments
77. @glennsarti Reference Conceptual Procedural Types of Documentation Getting Started READMEs Code Comments
78. @glennsarti Reference Conceptual Procedural Types of Documentation Getting Started READMEs Code Comments
79. @glennsarti Reference Conceptual Procedural Types of Documentation Getting Started READMEs Code Comments
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
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
82. @glennsarti
83. @glennsarti From Where Chat Email “Knowledge Bases” Forums Issue Trackers Meta-documents
84. @glennsarti From Where Chat Email “Knowledge Bases” Forums Issue Trackers Meta-documents
85. @glennsarti From Where Chat Email “Knowledge Bases” Forums Issue Trackers Meta-documents Asking Humans
86. @glennsarti To where?
87. @glennsarti Findable Readable Changeable
88. @glennsarti Demo
89. @glennsarti Demo https://sarti.dev/platyPS
90. @glennsarti Documentarian https://github.com/microsoft/Documentarian - https://sarti.dev/platyPS
91. @glennsarti - https://sarti.dev/platyPS
92. @glennsarti
93. @glennsarti
94. @glennsarti
95. @glennsarti
96. @glennsarti
97. @glennsarti
98. @glennsarti
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 ✅ ✅ ✅ ✅ ✅ ❌
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
101. @glennsarti
102. @glennsarti
103. @glennsarti Demo https://sarti.dev/platyPS
104. @glennsarti
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!
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
107. @glennsarti Resources Documentation as UX https://www.youtube.com/watch?v=0S0eAuGzjpI Docs for Developers https://docsfordevelopers.com @glennsarti