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. Β  Β  Β πŸŒ‰πŸŒŒ

πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—πŸ€—

NodeSummit

By LizTheDeveloper

NodeSummit

  • 2,230