Beginner's Mind
Writing Documentation for Newbies
Liz Howard
👩🎤👩💻👩🏫
enki.com
lizthedeveloper.com
@lizthedeveloper
I have worked in:
- AutoHotkey
- JavaScript (early web)
- JavaScript (today)
- AS400 Databases
- SQL
- Powershell
- PCL
- COBOL
- ASP.NET
- VBScript
- C++
- Visual Basic 3, 5 and 6
- C#
- ColdFusion
- Python
- ARGOStore
- ARGL
- PCL
- GCode
- R
- Java
- XSL Template (a turing complete language)
Learning a new environment sucks because of poor documentation
Beginner's Mind
(shoshin)
[add: illustrative koan about beginner's mind]
[add: super predictable stacked river stones picture]
Don't orient your documentation around your frame of reference. ☸️
Your customers aren't your team,
that's why they need the docs. 🤷♀️ 🤷♂️
What a junior developer can understand
gets used. 👧👦
If they teach it in a bootcamp
It's mainstream. 📈
Be learning a new skill,
always. 👩🎓👨🎓
Forge new territory;
learn things outside of software. 👩🏭👨🔧👩🌾👨🎤
Teach. 👩🏫👨🏫
This Talk
http://bit.ly/how-to-document
https://slides.com/lizh/nodesummit
All images and screenshots are linked to their source.
Open source checklists for documentation:
Where do we start?
#notallpackages
Small Tool 🛠
Library 📚
Low-Distribution Platform 🐯
High-Distribution Open-Source Platform 🐅
Platform-As-A-Service 🦍
What things are:
a Documentation Schema
Quickstart
🛠📚🐯🐅🦍
RunKit
Use
Your docs need to be playgrounds
Overview
📚🐯🐅🦍
Multiple audiences?
Choose-your-own-adventure
Overview
API Documentation
🛠📚🐯🐅🦍
API Documentation
API Documentation should be generated
Walkthroughs
📚🐅🦍
Demos
📚🐯🐅🦍
Walkthroughs and Demos
Better Together 🌈
Courses
A course isn't about content
Exercises
Junior Developers need a chance to practice first.
Courses
Instructional design (ID), or instructional systems design (ISD), is the practice of creating "instructional experiences which make the acquisition of knowledge and skill more efficient, effective, and appealing."
🐅? 🦍++
You don't know educational theory.
Hire an expert.
(if you can)
Emoji 🌈, Tone, and Diagrams
Emoji
🤓 - Pedantics
🛠 - Tool
❌ - Incomplete
✅ - Complete
👾 - Game
🌟 - Extra Credit
📚 - Book Resource
🦍 - Platform as a Service
🤠 - Unplanned Feature
😷 - Code Smell
👩🎤 - CTO
Emoji
🐛 - Bug
🦋 - Design Bug
🐞 - Won't Fix
🚨 - Urgent Issue
🎉 - Verified Fixed
Emoji
How many 🚨?
4
Org-wide: Use a consistent format
Tone
Tone
Not all junior developers are millenials
Create a tone styleguide that fits your audience
Diagrams
To help engineers on the autism spectrum
include a diagram
Don't incur documentation debt
😱😰🤦♀️🤷♂️
Review Cycles
What
How Often
API Documentation
Demos
Quickstarts
Continuous
Walkthroughs
6 Months
Courses
1 Year
Unmaintained Walkthroughs
📕 📗 📘 📙 = 🌏 🌍 🌎
Get your docs
translated.
Silicon Valley isn't the center of the universe. 🌉🌌
🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗🤗