Thinking Outside the Docs

Transcript

1. DOCS THINKING OUTSIDE THE
2. “They said Lamb couldn’t taste any better. Then a Sumerian cook tried this…” You won’t believe what they’re cooking In the palace kitchens of Ur!” “He added this one strange herb… And the entire city went wild!” Note: Translations are likely quite exaggerated.
4. “Mostly just lists of ingredients without further instructions” Assumes the reader has sufficient knowledge to figure out what to do next on their own “Beige and gloopy” results
5. People have struggled with documentation for thousands of years.
6. Sometime in the 80s…
8. Skills Music 78% Gardening 50% The Computers 75% Dad Jokes 90% Dad / Tinkerer / Musician Allen Smith About Me • Aspiring Mall Santa • Enjoys playing music, being outdoors, and minor-league baseball • World’s OKest developer • Ham: KO4ABW
9. ! " # $
10. The Friendly CMS We are probably not a cult.
11. Our Chat Today • Key definitions around documentation • The audience and intent of documentation • Documentation Ecosystems
12. What is documentation?
13. A curated collection of written, illustrated, animated, or interactive materials that helps people adopt, use, improve, and adapt a piece of software in the way that the author of the software intends. Adapted from Write The Docs & Others
14. The Code The Program
15. What is documentation not?
17. Who is documentation for?
18. Users
19. Developers
20. Machines
21. What is documentation for?
22. Adoption and Use Quality Assurance Adaptation and Improvement
23. Jobs to be Done Framework (JTBD)
24. Upgrade your user, not your product. Don’t build better cameras — build better photographers. — Kathy Sierra
25. Make people better.
26. How do I do [X]? How does this thing work? What are the fundamentals? What are all the capabilities?
27. We love us a good system.
28. They make us better. Documentation systems are for winners!
29. Díataxis https://diataxis.fr/
30. Díataxis Acquisition Application
31. Díataxis Acquisition Application Action Cognition
32. Díataxis Acquisition Application Action Cognition Working+Practice Working+Theory Studying+Theory Studying+Practice
33. Application Action How-to Guides (Working-Practice) •Outcome oriented •Examples: •Getting Started •Setting up a Dev Environment •Contributing
34. Acquisition Action Tutorials (Studying-Practice) •Skill oriented •Examples: •Railscasts •“How to build a plugin” •HTML Goodies, W3Schools (kind of in the middle)
36. Acquisition Cognition Explanation (Studying-Theory) •Understanding oriented •Reflection and connection are key •Examples: •Django Conceptual Docs •Explainer Videos •Design Patterns (GOF)
38. Application Cognition Reference (Working-Theory) •Information oriented •Helps with decision making •Examples: •Microsoft Reference Source •Umbraco Code Reference •Django API Reference
40. Díataxis Acquisition Application Action Cognition Guides Reference Explanation Tutorials
42. Documentation Ecosystems
43. Wrangling Resources
44. Developer Portals
45. Information Architecture
47. Discoverability It looks like you’re talking about documentation discoverability….
49. Right Time and Place It looks like you’re talking about documentation discoverability….
50. Community-driven Docs
52. Write about something that matters to you.
53. Thanks!
54. Q&A
55. The Friendly CMS