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

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 “ 

… 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 “ 

@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 … “ 

No content

@glennsarti 

No content

@glennsarti 

@glennsarti 

@glennsarti 

@glennsarti Icons Colour 

@glennsarti CLI Applications 

@glennsarti 

@glennsarti 

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

@glennsarti > kubectl get pod example-pod1 

@glennsarti > docker plugin create [OPTIONS] 

@glennsarti > docker start my_container 

@glennsarti > docker ps > docker rm > docker top 

@glennsarti > docker rmi my_image 

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

@glennsarti Aside : Metaphors 

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

@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. “ 

@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. “ 

@glennsarti Where’s the docs? 

@glennsarti Where’s the docs? 

@glennsarti 

@glennsarti 

@glennsarti 

@glennsarti 

@glennsarti First use Where’s the docs? 

@glennsarti First use Failures Where’s the docs? 

@glennsarti 

@glennsarti 🔊 🔊 🔊 🔊 🔊 🔊 🔊 🔊 

@glennsarti First use Failures Where’s the docs? 

@glennsarti 

@glennsarti Service Manual Install manual 

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

@glennsarti First use Failures Modifications UX, Pwsh and Docs 

@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 

@glennsarti Get-Help UX, Pwsh and Docs 

@glennsarti UX, Pwsh and Docs 

@glennsarti UX, Pwsh and Docs 

@glennsarti UX, Pwsh and Docs 

@glennsarti First use Failures Modifications UX, Pwsh and Docs 

@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 

@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 

@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 

@glennsarti First use Failures Modifications UX, Pwsh and Docs 

@glennsarti UX, Pwsh and Docs 

@glennsarti UX, Pwsh and Docs 

@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 ... 🥱 

@glennsarti UX, Pwsh and Docs 

@glennsarti Documentation is part of the UX. 

@glennsarti Documentation is part of the UX. 

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

@glennsarti What & Who 

@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 

@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 

@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 

@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 

@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 

@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 

@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/ 

@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 

@glennsarti Types of Documentation 

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

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

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

@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 

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

@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 

@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.) 

@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. “ 

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

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

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

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

@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 

@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 

@glennsarti 

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

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

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

@glennsarti To where? 

@glennsarti Findable Readable Changeable 

@glennsarti Demo 

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

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

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

@glennsarti 

@glennsarti 

@glennsarti 

@glennsarti 

@glennsarti 

@glennsarti 

@glennsarti 

@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 ✅ ✅ ✅ ✅ ✅ ❌ 

@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 

@glennsarti 

@glennsarti 

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

@glennsarti 

@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! 

@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 

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