Skip Main Navigation

Tooling over docs

Why you should prioritize building tooling to shape best practices instead of writing docs

17 December 2020 · 1 min read

  • I ❤️ docs

    • MDN docs
    • semantic-release docs
    • React docs
    • Storybook migration docs
  • Written thousands of lines of docs outlining best practices over the years at companies

    • Newcomers or casual devs want best practices docs to help them do the right thing before PRs
    • They also don’t wanna spend countless hours trying to figure out how to do the right thing
  • But unfortunately

    • People don’t read docs (myself included)
    • Best practice docs get stale quickly
    • because they are separated from actual code
    • because there’s no one who’s responsibility is just the docs
    • With how quickly tech changes, stale docs could be showing anti-patterns
  • People think tooling is just for making their lives easier

    • Doing heavy lifting for devs
    • CRA, Netlify, Jest, etc.
  • Types of tooling?

    • Generators (plop or yeoman) replace step by step set ups
  • That’s the main use for tooling, but it can also be a teaching tool
  • Linting

    • Many lint rules aren’t errors, but best practices to avoid gotchas
    • But each rule has a page explaining the rationale and the correct way
    • Imagine having to rewrite each one of those explanations in a best practices doc
    • List out all the eslint plugins
    • Example or two lint rules
  • TypeScript?
  • Lighthouse CI

    • Each failure directs you to more docs
  • When you find yourself needing to teach or train people on best practices

    • Do live sessions
    • But consider using tooling for long-lasting info over writing docs
    • The tooling basically points back to a shared location of docs

Keep learning my friends. 🤓

Hi, I'm Ben Ilegbodu. 👋🏾

I'm a Christian, husband, and father of 3, with 15+ years of professional experience developing user interfaces for the Web. I'm a Principal Frontend Engineer at Stitch Fix, frontend development teacher, Google Developer Expert, and Microsoft MVP. I love helping developers level up their frontend skills.

Discuss on Twitter // Edit on Github

Attend upcoming minishops

Minishops by Ben Ilegbodu are fully-remote workshops that last about 3 hours. They’re highly-focused, covering only the concepts you want to learn so that you can level up your skills and get on with the rest of your day.