RT @DeliberateComp1: "How cognitive biases and ranking can foster an ineffective architecture and design" Don't miss out on… https://t.co/Njau4ATXn0
This talk was presented at API The Docs Virtual 2020 event series on 24 June. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit our talk recaps ToC page for an overview of all presentations!
Lead Product Language Writer at New Relic
Technical Trainer
New Relic hired an external trainer to teach members of the Tech Docs and UX teams REST API documentation best practices.
Tthe team members already learnt about API reference writing through documenting them, and from classes aimed at engineers. Emphatic knowledge gaps appeared on a fundamental level.
Consider the audience: mixed background, typical techwriter level but not engineer --» explain technical topics more slowly, explicitly. Do not assume programming experience: Fine-tune to audience needs because training takes a lot of resources. Small class.
Adjust agenda to student interest, address concepts.
Ensure low-friction interactivity, but not command-performance: frequently scheduled breaks for questions.
Liven up tech content: move out of technology often, with interesting and relevant examples.
The 80/20 rule: teach the first 20%, and students can self-teach the rest if they meet it.
Boundaries around content for beginners, to inspire and empower, to reduce impostor syndrome or paralysis from overwhelm.
Multimodal learning: first learn. Then practice in frequent small labs. Then make students answer other students' questions, the act of explanation consolidates their own understanding.
Higher confidence in discussions on:
Being able to ask more directed, particular questions around the APIs they are documenting.
RT @DeliberateComp1: "How cognitive biases and ranking can foster an ineffective architecture and design" Don't miss out on… https://t.co/Njau4ATXn0
RT @DeliberateComp1: "APIs: Semi-permeable, osmotic interfaces" Don't miss out on @dawnahukanna's talk next week at the… https://t.co/rF2qm9E2WM
Deliberate Complexity 2022 features a series of three events organized by @pronovix with the intent to create a spa… https://t.co/5ZkCEKHS7S
Deliberate Complexity 2022 features a series of three events organized by @pronovix with the intent to create a spa… https://t.co/uFiX820fCE
Big thanks to @palantir and @pronovix for sponsoring the #drupal update project bot. This tool is a major reason… https://t.co/OVYevQEFLG