Field Notes

Nathaniel Schutta and Neal Ford: Communicating Architecture

Janet Riley — Tue, 19 Jul 2022 12:57:16 GMT

Summary

Neal Ford hosts Software Architecture Hour, a series of live conversations on O'Reilly. He spoke with Nathaniel Schutta on Communicating Architecture on 7/7/2022.

Notes

Is presentation patterns still relevant?

Yes.

Ford described new patterns for Zoom:

Start with the punchline. You must immediately state what they're going to get out of it so they don't leave. In-person, people will let it ride for a bit before they get up.
Paired presentations work better because it's more like a conversation
Timing is more important. Make something change on the slide every 30 seconds so it's not static and creates a sense of motion.
Ford: quoting a professor's advice - you need to do something every 10 minutes to hook people back in.

What presentation software is best?

Keynote or Powerpoint both have good animations. "You want a rich way to manipulate time" .
Info decks have to be complete; presentations are only half complete because the presenter is the other half.

Favorite tools

The simplest ones. Whiteboards.
Excalidraw
Miro

Use a tool that has layers. Ford puts the boxes on the bottom layer, protocols on the next, transactional boundaries above that.

Favorite diagramming frameworks

C4, Archimate, boxes and arrows with a legend. Use the framework that works. Keep diagrams up-to-date.

Ford shared a story about a coworker who would draw diagrams by hand as he talked with people, over and over. "It was a fantastic stupid human trick." High impact on the audience. ... "You start to see how they got to [their design]"

Miscellaneous:

Ask, what nugget or two do I want my audience to leave with?

Focus on narrative.

Quiz questions and "raise your hand if..." gets mixed results. Some people are into it, some online audiences are shy

Excerpts

Ford: "As an architect, I have two folders - Current and Archaeology". Ford updates the Current diagrams, ignores Archaeology.

Takeaways

With Zoom it's harder than ever to retain attention.

Use layers in diagrams to add another dimension. I'd like to explore this for breaking up layers as Ford described, especially as a way to start with a simple idea and build on it. Something in this and in the Presentation Patterns chapter on temporal patterns reminds me of Scott McCloud's Understanding Comics. McCloud shows a sequence of two illustrations, with a person wearing a hat, and in the next panel, raising it. Our brains fill in the space between to create a story. Could I tap into that and a sequence to make diagrams convey more?

Curling Resources

Janet Riley — Sun, 19 Jun 2022 20:00:24 GMT

Overview

How to Watch Curling Like a Pro

Technique

Jamie Sinclair's Learn to Curl series explains all the basics and then some.

Curling Class has resources and videos.

Sweeping Saturdays has balance and conditioning exercises off the ice.

Rules and Strategy

The Rules of Curling

Basics of Curling Strategy "covers everything a first-time skip needs to know to call a game, and gives insight into the general strategies used."

Digital Gardens

Janet Riley — Wed, 15 Jun 2022 00:16:30 GMT

Andy Matuschak's Evergreen notes made me curious about starting my own digital garden. Matuschak's distills and connects his research, building an accumulation of insight. I'd like to capture and link more of what I take in and see what patterns it makes.

Maggie Appleton's tools and resources for digital gardeners lists tools for creating public or private digital gardens.

How Browsers Work

Janet Riley — Sun, 12 Jun 2022 20:48:53 GMT

Web Browser Engineering

Web Browser Engineering Author:Pavel Panchekha & Chris Harrelson

Summary:

Manchekha and Harrelson explain how browsers work. The textbook guides you through building a basic web browser in Python.

Chrome Developer series: Inside Look at Modern Web Browser

Summary:

A four part deep dive on Chrome

Links:

Part 1: CPU, GPU, Memory, and Multi-Process Architecture

Part 2: What happens in navigation

Part 3: Inner Workings of a Renderer Process

Part 4: Input is Coming to the Compositor

Dan Slimmon: An Incident Command Training Handbook

Janet Riley — Thu, 26 May 2022 18:30:55 GMT

Dan Slimmon: An Incident Command Training Handbook

Summary

How to structure and lead an incident response. The five questions of a status update. How to manage information flow effectively.

Slimmon's writing style is direct and simple. It's a mid-length article with some detail, but you could follow it in a high-stress situation (like mid-incident) and benefit immediately.

Best case scenario is to have the whole team read it ahead of time to understand the structure. When it's showtime everyone can slide into their roles and know their responsibilities.

Excerpts

An Incident Commander’s job is to keep the incident moving toward resolution. 
But an Incident Commander’s job is not to fix the problem.

As Incident Commander, you shouldn’t touch a terminal or search for a graph 
or kick off a deploy unless you’re absolutely the only person available to do it. 
This may feel uncomfortable, especially if your background is in engineering. 
It will probably feel like you’re not doing enough to help. 
What you need to remember is this: whatever your usual job, when you’re the Incident Commander, your job is to be the Incident Commander.

Managing information flow is the single most important responsibility of the Incident Commander.

Takeaways

Sometimes the most effective thing you can do is coordinate the experts.

John Graham: Building an Engineering Roadmap

Janet Riley — Thu, 26 May 2022 18:07:36 GMT

John Graham: Maximize your team. How I created an Engineering Roadmap

Summary

Graham walks through creating his first engineering roadmap. Goals, format, ranking criteria.

Nikola Resources

Janet Riley — Thu, 26 May 2022 17:33:41 GMT

Nikola is the static site generator used to render this site. It's written in Python.

Getting Started

The Nikola handbook Creating a site (not a blog) with Nikola Creating a Nikola theme and Theming

Plugins

Extending Nikola

Writing task plugins for Nikola

Controlling task execution order in Nikola

Nikola uses DoIt. Plugin classes are derived from DoIt Tasks.

Migrations

Some practical details - adding search, enabling notebooks, teasers, auto-posting to other sites

More customization notes from Louis Tiao

Docs for Developers: An Engineers Field Guide to Technical Writing

Janet Riley — Wed, 25 May 2022 17:00:00 GMT

Docs for Developers: An Engineer's Field Guide to Technical Writing

Publisher's Page

Author: Jared Bhatti, David Nunez, Jen Lambourne, Zachary Sarah Corleissen, Heidi Waterhouse

Summary

How to write maintainable docs that help your customers use your software.

Excerpt

"Docs for Developers demystifies the process of creating great developer documentation, following a team of software developers as they work to launch a new product. At each step along the way, you learn through examples, templates, and principles how to create, measure, and maintain documentation, which you can adapt to the needs of your own organization."

Takeaways

This struck me as the devops of documentation - turn these high level ideas into something we can live in. On my To Read pile.

Gitlab: Technical Writing Fundamentals

Janet Riley — Wed, 25 May 2022 17:00:00 GMT

GitLab's Technical Writing Fundamentals course

Summary

Written to help contributors write and edit GitLab documentation. The first three parts are grammar and style guidance. Session 4 covers how to approach four topic types: concepts, tasks, references, and troubleshooting.

The page links to the recorded versions on YouTube.

Google: Tech Writing Resources for Developers

Janet Riley — Wed, 25 May 2022 17:00:00 GMT

Google's Tech Writing Resources for Developers

Summary

Google's Technical writing courses and resources for engineers and engineer-adjacent folks.

Excerpt

"This collection of courses and learning resources aims to improve your technical documentation. Learn how to plan and author technical documents."

Field Notes

Nathaniel Schutta and Neal Ford: Communicating Architecture

Summary

Notes

Is presentation patterns still relevant?

What presentation software is best?

Favorite tools

Favorite diagramming frameworks

Miscellaneous:

Excerpts

Takeaways

See Also

Curling Resources

Overview

Technique

Rules and Strategy

Digital Gardens

How Browsers Work

Web Browser Engineering

Summary:

Chrome Developer series: Inside Look at Modern Web Browser

Summary:

Links:

Dan Slimmon: An Incident Command Training Handbook

Summary

Excerpts

Takeaways

John Graham: Building an Engineering Roadmap

Summary

Nikola Resources

Getting Started

Plugins

Migrations

Docs for Developers: An Engineers Field Guide to Technical Writing

Summary

Excerpt

Takeaways

Gitlab: Technical Writing Fundamentals

Summary

Google: Tech Writing Resources for Developers

Summary

Excerpt