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:

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
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
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:

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

Things to think about when planning:

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?
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.
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