Documentation as UX: Rightfully Writing the Right Things

Presentation on the threefold model of documentation, the many forms of documentation, and tips and advice to help humans produce more and better documentation for their teammates, customers, and future selves.

Transcript

1. DOCUMENTATION AS UX: RIGHTFULLY WRITING THE RIGHT THINGS Navigate : Space / Arrow Keys | - Menu | - Fullscreen | - Overview | - Blackout | - Speaker | - Help M F O B S ?  1 / 53
2. WHO AM I? Co-organizer of the , sometime host of , frequent contributor to open source PowerShell projects, Puppet so ware engineer, documentarian at heart. (Get-Item Speakers:\Lombardi).Synopsis STLPSUG ChatterOps [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  2 / 53
3. UX? [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  3 / 53
4. UX ... all aspects of the end-user's interaction with the company, its services, and its products Don Norman and Jakob Nielsen [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  4 / 53
5. FOR A CLI, THOUGH? [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  5 / 53
6. DEFINITELY ... submarine warfare. You're in an unfriendly environment. Any sort of breach in the system or error in your process could cause catastrophic damage... Randall Hansen [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  6 / 53
7. A DEEP RABBIT HOLE Navigation Structure Semantics Visual Organization Color Usage Expectations [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  7 / 53
8. DOCUMENTATION: Artifacts that explain something in sufficient detail Me, for this presentation [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  8 / 53
9. THREE TYPES OF DOCS TO WRITE Reference Narrative Concept [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  9 / 53
10. AND IN YOUR REPOS COMMIT THEM Plaintext In a Repository So it can be Diff'd And You Can See the History [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  10 / 53
11. PLAINTEXT This is _some_ markdown text. It's got **markup**. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  11 / 53
12. IN A REPO (With your code) [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  12 / 53
13. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  13 / 53
14. DIFFING Being able to check precisely how your code has changed is awesome. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  14 / 53
15. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  15 / 53
16. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  16 / 53
17. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  17 / 53
18. HISTORY The blatant magic of source control [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  18 / 53
19. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  19 / 53
20. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  20 / 53
21. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  21 / 53
22. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  22 / 53
23. ASIDE: SCOPE AND AUDIENCES Projects and Scope, Internal vs External [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  23 / 53
24. 1. REFERENCE DOCS Explain the technical details and usage of a project Nearly Ubiquitous Unforgivable if missing Insufficient [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  24 / 53
25. POWERSHELL Comment-Based Help about_topic PlatyPS [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  25 / 53
26. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  26 / 53
27. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  27 / 53
28. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  28 / 53
29. 2. NARRATIVE DOCS Explain how and why a user can/should do a thing Use the structure of a story Diggers of Pits of Success Usually written by outsiders Most effective type [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  29 / 53
30. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  30 / 53
31. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  31 / 53
32. 3. CONCEPT DOCS Answer a specific question Least common type Mandatory if you want an actually-good UX [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  32 / 53
33. CONCEPT QUESTIONS Why did you choose this specific design? How does this internal component work and why was it used? When should I (not?) use a particular feature or component? What do I do when implementing this project in the my environment? Which patterns are best practices and which ones should I avoid? [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  33 / 53
34. ASIDE: INTERNAL VS EXTERNAL Internal users and teammates matter too [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  34 / 53
35. THREE TYPES, UNCOUNTABLE FORMS [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  35 / 53
36. Centralized Docs Static Sites, Wikis, Confluence et al GitHub/GitLab Templates Emails [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  36 / 53
37. Chat Slack, Teams, Mattermost, Hipchat Forums, stack overflow Blogs [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  37 / 53
38. Metadocuments Commit logs Issue comments Ticket data License Changelog Contributing [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  38 / 53
39. Documentation in Code Tests Code comments Inline docs [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  39 / 53
40. NON-WRITTEN DOCS [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  40 / 53
41. Audio Podcast, voice over Video Tutorials, recordings, lectures Live Labs, Q&A [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  41 / 53
42. FOCUS Documenting a PowerShell Module [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  42 / 53
43. STUDY: DOCUMENTARIAN Find-Module -Name 'documentarian' ` | Install-Module -Force -Scope CurrentUser [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  43 / 53
44. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  44 / 53
45. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  45 / 53
46. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  46 / 53
47. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  47 / 53
48. TAKEAWAYS Docs live as close to code as possible Write more than just reference docs Words matter Write and design specifically Dont't forget the many forms Iterate [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  48 / 53
49. RESOURCES Needful Docs Write the Docs June Blender's PowerShell Help Deep Dive Markdown Guide http://michaeltlombardi.gitlab.io/needful-docs/ http://www.writethedocs.org/ https://github.com/juneb/PowerShellHelpDeepDive https://www.markdownguide.org/ [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  49 / 53
50. MORE RESOURCES Tracy Osborne's Medium post ) Gender-neutral Technical Writing via TechWhirl ) https://medium.com/@limedaring/five-tips-for- improving-your-technical-writing-and- documentation-47353723c8a7 https://techwhirl.com/gender-neutral-technical- writing/ [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  50 / 53
51. EVEN MORE RESOURCES Steve Konves's post on HackerNoon ) Jacob Kaplan-Moss on Writing Great Documentation ) https://hackernoon.com/write-good- documentation-6caffb9082b4 https://jacobian.org/writing/great- documentation/ [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  51 / 53
52. APPLAUSE AND/OR HECKLING Yell at me on: Break my stuff, file issues, call me out. Twitter @barbariankb LinkedIn Github GitLab [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  52 / 53
53. THANK YOU! Please use the event app or sched.com to submit a session rating. [ GitPitch @ gitlab/michaeltlombardi/documentarian/gitpitch ]  53 / 53