Running Amok: Igniting a Documentation Revolution - Jon Pretty
Channel: ScalaIO FR
Date: 10/02/2020

Running Amok: Igniting a Documentation Revolution - Jon Pretty

Why is our ecosystem littered with so much incomplete, out-of-date and inadequate documentation? Why can't we check a library's v1.3.5 docs and read about how it contains a bug that's fixed in v1.3.6? Why can't a humble user contribute an improvement to the docs without involving the project maintainer, and having a new release made? Why does the documentation contain examples which don't compile? Why must we wait longer for a release of a library when only its docs are missing? Documentation needs to evolve faster, and to continue improving even after the software it describes has stopped. We need a documentation revolution! This talk will take a philosophical analysis of the causes of our industry's bad documentation culture and how our incumbent tooling and practises aren't helping. I will introduce Amok, a revolutionary new documentation management tool built upon Fury, for creating, maintaining, evolving, linking, versioning and checking documentation. Amok will take advantage of static build information which is now available thanks to Fury, and provide solutions to all the awkward questions above.