Placemaking and Productivity: Build Maintainable Broad-scale Tools with a Small Team

As we bring on new team members, we want to ensure they can ramp up quickly and have a good experience. They should be able to understand "the company way" of accomplishing things and quickly find the tools they need to do their job. Veteran team members should also be able to codify and commoditize the patterns they've developed over time so they can focus on higher-order problems. In large organizations, such tooling might be the purview of a dedicated platform engineering team and have a budget to match. But what if you're a small team, or a team of one, and you want to build something that scales to the whole organization without becoming a full-time job? At ITHAKA, over 100 engineering staff manage hundreds of applications in a handful of languages and frameworks across many teams and products. Despite the variety, most of those engineers still need to perform a core set of tasks when developing, from debugging to traffic routing to feature toggles. Teams are always working on high-priority projects, and it can be difficult to find the time to take stock of things that can be better streamlined or automated. Further, although we have a platform engineering team, as a non-profit we don't have the budget for someone to work on meta-tooling as a full-time job. Over time, several aspects of our development process have become common sources of friction, with a lot of time spent answering questions or debugging local machine setups. In this talk I'll tell the story of my journey to build a tool with a net positive return on investment, from the initial idea to the rollout and adoption. I'll cover the principles that guided my decisions, the tools we use, and the outcomes we've seen so far.

Transcript

1. Placemaking and Productivity Build Maintainable Broad-scale Tools With a Small Team Dane Hillard Technical Architect, ITHAKA @dane.dev
2. Kartik
3. How do I tail the logs for an application? Oh, here’s a doc about that!
4. How do I check the routing for my application? Ah, there’s a script for that. It lives in this repository. Er, or was it this one?
5. How do I do local development for this application? You’ll need, uh, a few things for that.
6. I think I get it? I’ve been taking some notes. Hey, how’s your onboarding going?
9. Fowler, Martin. “Design Stamina Hypothesis.” martinFowler.com, 20 June 2007, https://martinfowler.com/bliki/DesignStaminaHypothesis.html.
10. Drive down cost
11. Spend time on higher-order problems
16. “Glue” work
17. “Glue” work • Follow service logs • Look up service IP address • Configure network routing • Create a new S3 bucket • Run a local environment proxy • Scan for vulnerabilities • ... • 😭
20. It’s easy, just kubectl … | jq … | xargs …
21. Death by 1e3 paper cuts
22. pain ∝ N teams * Size team * N tools * N migrations * (1 + R turnover )
23. The birth of a CLI
24. Shell script → ???
26. Needs • Installation • Usage • Upgrades • Contribution • Impact • Advocacy
27. Installation
28. Installation • Available from everywhere on your machine • Using our existing Python ecosystem • You only need to know the ithaka name
29. • Published Python package • pypa/pipx • PEP 621 ◦ [project.scripts] ithaka = “ithaka.main:main” Installation
30. • Published Python package • pypa/pipx uv? • PEP 621 ◦ [project.scripts] ithaka = “ithaka.main:main” Installation
31. Usage
32. Principles • Support self-discoverability • Teach the underlying commands where possible • Provide actionable feedback • Don’t reinvent good tools; integrate them
33. • tiangolo/typer ◦ pallets/click Usage
38. • Textualize/rich Usage
40. Usage • Textualize/trogon ◦ Textualize/textual
42. Plugins + custom scripts
44. Plugins • pypa/packaging • importlib • PEP 621 ◦ [project.entry-points.ithaka_cli] <name> = "cli_plugin_<name>.plugin" ▪ Shoutout to pytest • pipx inject ◦ Decouples you from extras!
45. Custom scripts • PATH ◦ Find executables named ithaka-cli-<name> ◦ Make available as a command named <name>
46. Frameworks CLI → tiangolo/typer Rich text → Textualize/rich TUI → Textualize/trogon Installation + plugins → pypa/pipx → importlib → pypa/packaging
48. Contribution
49. Contribution (technical) • pipx install --suffix dev ◦ Editable installs • Working plugin exemplar
50. Contribution (sociotechnical) • Help power users solve their problems • Design intentionally ◦ Adding new features is easy ◦ Updating features is easy ◦ Codify common patterns ▪ Precondition checks • Guardrails ◦ Healthy test coverage ◦ Documentation ◦ Formatting ◦ Linting ◦ Type checking ◦ Dependency management
51. Impact
57. Advocacy
58. Advocacy • Create a community channel ◦ Questions ◦ Feedback ◦ Shoutouts ◦ Announcements • Find alignment to other campaigns ◦ Better Together® • Create a great developer experience ◦ Technical and sociotechnical
59. minimal-pba-cli
60. Demo
62. Q & A
63. Epilogue
64. Recommended watching