Notes from RubyConf2020 Day 1

Published Tuesday, November 17, 2020

Matz’ keynote

Everyone loves Github If Matz says it, it must be true

Ruby 3 will be released as planned in December. Was supposed to be related to Tokyo Olympics, but not anymore.

Highlights:

  1. Compatibility
    • Backwards compatibility with Ruby 2.X without any modifications (!!)
    • Why? We know from past experience that compatibility matters
    • Example: Encoding (Ruby 1.X to 2.X)
    • Community split for more than 5 years!
      • Other languages experienced this too (Python3, PHP6, ECMAScript4)
    • Designing a language is hard
      • Hard to correct past mistakes
      • Fixes introduce incompatibily
      • Always need updates, improvements
      • Tension: Programmers love new things, but hate pain forced by new things
  2. Performance
    • Again, we know from previous version updates that performance matters
    • Ruby 1.9 tragedy (?)
    • In Ruby, split lasted 5 years vs Python3 split lasted 15 years
    • Ruby is fast enough
    • “Everyone loves GitHub” @Matz is a superfan <3
  3. tbd (had to step away from talk, will watch the recording later)

Improve Your Technical Writing Workshop with Noel Rappin

What makes the software industry work? GOOD TECH WRITING.

  • Docs
  • Blog post
  • Comments

Good tech writing:

  • Helps popularize technologies
  • Helps get people unstuck
  • Helps you in your career
    • I can clearly explain limitations, requirements, possibilities, etc
    • Tremendously valuable

Basic Goal: reader should understand something they didn’t understand before.

Benefits:

  • You’ll learn something
  • Evidence of your expertise
  • Helps others
  • Advocate for something you’re excited about

Analogy: “Write cricket bats and make our ideas travel” (Jeremy Irons in a cool play that I don’t remember the title of)

Important reminder: You don’t have to be an expert to write about how to do something

Best time to write about something: right after you learn it

  • Reinforces learning
  • Helpful to write from a “newbie” fresh eyes perspective
  • The further you get from the time you learned something, the harder it is to get back in that headspace of the person who doesn’t know the thing you now know
    • If you can’t get back in that headspace, find a novice. Ask them for feedback

What to write about?

  • Something you want to learn about
  • Something you want to be associated with

Topic ideas:

  1. How to pitch and ship a small feature (“delete directory”)
  2. Pastejacking: what it is and how to protect against it
  3. How to Speak Up: A Quiet Person’s Guide to Making Yourself Heard

Things to think about when planning:

  1. Problem
    • Good chance you’ve focused on the solution
    • What problem is the reader having? What brought them to your post?
    • How will what I’m writing solve this problem?
    • Helps give you focus
    • Helps reader connect with the material
    • Come up with a problem statement
    • Example: “The problem is…”
      • For topic 1 above:
        • You want to progress in your career
        • You want experience as a feature lead to progress in your career
        • You want experience shipping a feature end-to-end
        • You have an idea to improve your product, but not sure how to get it off the ground
      • For topic 2 above:
        • You want to provide commands that are safe for your readers to copy and paste into their terminal
        • You want to help readers by providing specific commands they should run on their local machine, but you don’t want to accidentally open up an attack vector for bad actors
        • You have a feature that prompts users to copy/paste commands into their terminal, and you want to make sure it’s safe
        • Commands you can copy/paste to run locally are super helpful, but how do you make sure they’re also super safe?
        • There’s lots of ways for bad actors to exploit seemingly benign features, like a dialog that provides commands your users can run locally. Here’s how to make sure you’re keeping your users safe.
        • ZOMG did you know that “pastejacking” is a thing?
  2. Reader
    • What does the reader already know? (beginner, intermediate, or expert)
    • What does the reader not care about?
    • What do you want the reader to take away?
    • Example prompt: “What does your reader know? What don’t they know?”
    • For topic 1 above:
      • Things they know:
        • Their product
        • Their new idea for improving their product (maybe)
      • Things they don’t know:
        • How to come up with feature ideas
        • How to validate your feature idea
          • How to gather data
          • Where to go for data
        • How to pitch the idea
    • For topic 2 above:
      • Things they know:
        • Some familiarity with bash, terminal commands
      • Things they don’t know:
        • What pastejacking is
        • How attackers can use it to exploit end users
        • What to protect against
        • How to evaluate whether feature X is exploitable via pastejacking
      • Reader is someone who develops for the web (or designs products for the web), but isn’t an appsec / infosec expert.
  3. Oh no, I missed the third thing

Process:

  • Write a sentence that starts “My perspective is different because…”
    • For topic 1 above:
      • “…I’m an engineer, and I don’t usually do feature ideation, customer research, or pitching.”
      • “…I recently got promoted, and shipping the feature end-to-end was a big part of it.”
    • For topic 2 above:
    • “…I’m not an expert in appsec, just someone who had to patch this security hole recently.”
    • “…I just learned about this, and I think it’s super interesting and want to draw other people’s attention to it.”
    • “…I haven’t thought about this as a security risk before, so there’s a chance you haven’t either.”

Side note: Noel loves answering questions because that’s the only time he knows he’s providing content the audience actually wants.

Structure:

  • Examples:
    • You think this is impossible, but it’s not impossible
    • I want to tell you about this crazy bug hunt
    • “By now you’re probably wondering why…”

Storytelling:

  • Classic for a reason: hero slays a monster
    • Tell the story in order successfully
    • Think about the beats of the story
    • There’s a goal that tees up the next goal
      • What do you need to explain in each step?
      • The reader doesn’t know what you know
    • How do you go from step to step and why?
      • What do I learn in this step?
      • How does it get me to the next step?
    • Having trouble with story beats? Maybe you need to reevaluate your topic, audience, etc.

Write out the first few beats of your story:

  • For topic 1 above:
    1. I want to pitch an idea, but I don’t know how to come up with one
      • Present why you want to pitch
      • Present problem statement, then go about solving it
    2. Here’s how I brainstormed ideas
      • End result: list of pitchable ideas
      • Next step: how do I choose the strongest one?
    3. Here’s how I chose the strongest one
      • End result: ok, we’ve got our feature we want to pitch
      • Next step: how do I pitch it?
    4. Here’s how I pitched it
      • End result: ok it’s pitched
      • Next step: It got approved! Now what?
    5. Profit
  • For topic 2 above:
    1. Oh no! We got a security vulnerability report about pastejacking
      • That stinks for you, why do I care?
    2. Explain what pastejacking is
      • Cool, now I know what it is, but why do I care?
    3. Explain potential exploits (how it can hurt your users)
      • Yikes! Alright, I’m good and scared. How do I know if I’m vulnerable to this?
    4. Outline some things to look out for when designing/developing features
      • Thanks, I’ll be mindful of these in the future. But what if it’s already too late? How can I patch a vulnerability?
    5. Explain how we fixed our case
      • Cool, what about my case, which might be different?
    6. Explain some other common fixes (maybe?)

General Advice:

  • Any interesting code sample has extra complexity
    • Simplified examples can seem silly
    • TEST YOUR EXAMPLES on the finished draft
      • Ask your sample readers to do this too
  • Avoid using technical terms in non-technical context
    • Minimize barriers between you and your audience
    • Maximize things that make your ideas “springy” (remember cricket bat analogy)
  • Don’t say things are “easy” or “obvious”
  • Don’t worry about over-explaining
  • Avoid using “this” without a referrent (“this allows you to…” vs “this method allows you to…”)
  • Read it out loud
  • Check “we’ll talk about this later” – make sure you actually did

Q&A:

  • How to benchmark ideas / guage interest in ideas?
    • No cost to writing something and publishing it (except your time/energy)
    • The act of finishing/publishing is important in and of itself
  • Where to put code snippets/examples?
    • Repo, gist, codepen
  • Keep content up-to-date?
    • Eh, just add a publish date and disclaimer

The State of Ruby 3 Typing (Soutaro Matsumoto)

Existing type checkers:

  • Steep
    • Static type checker
    • Written in Ruby
  • TypeProf
    • Infers types
  • Sorbet
  • RDL

Ruby type checker: ruby/rbs

  • RBS is a type definition language
  • Steep already uses RBS as the primary type language
  • TypeProf reads library types from RBS and generates RBS
  • Sorbet uses RBI as its native declaration language, will eventually support RBS too (but maybe only a subset)

RBS Features

  • Generics (Array[Integer], Hash[String, Array[Integer]])
  • Union types (String | Symbol, Array[String | Integer])
  • Interface types
    • Supports duck typing
  • Untyped type (def eval: (String) -> untyped)

RBS for Gems

  • Stdlib types
    • Defined by Ruby core team
  • Gem types
    • Defined by Gem authors, contributors
  • App types
    • Defined by developer of th app

Why is RBS a seprate library?

  • Matz believes type annotations will be outdated in the future
  • Keep type checking in Ruby optional
  • Support libraries written in C

Writing types in Ruby code is out of scope of RBS. But type checkers need inline type annotations…how does that work?

Future work:

  • Develop “RBS of Gems”
    • Request: publish to ruby/gem_rbs
    • Save RBS files in gems/gem_name/version
  • Release gems with RBS
    • Add sig directory and put RBS files in there
    • Generate RBS from Ruby code:
      • rbs prototype rb lib/**/*.rb
      • typeprof exe/goodcheck

Summary:

  • Ruby 3 will ship with a feature to support type checkers
  • Several type checkers are available
  • Check out ruby/gem_rbs

Escape Room

SO MUCH FUN