A Rubric for Open Source Documentation

August 23, 2019

In reference to my last post, someone pointed me to the Eventide Project, and my response was that I could not understand what the project was, what it did, or how it worked, despite volumes of documentation. Rather than detail out that project’s documentation failings, I thought it might be interesting to see a rubric that walks you through the information you need to give new and existing users the best information about an open source project.

Event Sourcing in the Small

August 14, 2019

I’ve been fascinated by event-sourced architectures and wanted to get some real experience with it, but I also didn’t want to set up massive infrastructure inside AWS, find 100 developers to test it out on, and potentially ruin a business by doing so.

So I created an application that I believe mimics the developer workflows and architectural decisions you have to make in order to add features to an event-sourced architecture and want to share what I found. Anyone who has done this in the large, would love to hear if this tracks with your experience.

My takeaways are that it encourages some good practices, creates handy de-coupling between components, but introduces some friction, as well as complication for building a UI.

Let’s see how.

Choosing Technology

August 08, 2019

Choosing technology has a huge impact on a team’s performance, and when you are starting out, you have a lot of decisions to make. We often get hung up on technical features, or weather we should use a framework or a bunch of libraries. The reality is you have to gain a deep understanding of the business realities coupled with your team’s values. From there, you then evaluate your startup cost (opportunity cost) against the cost to maintain the system over time (carrying cost) to arrive at the best decision. Technical features are a part, but a small one.

Four Better Rules for Software Design

July 25, 2019

Martin Fowler recently tweeted a link to his blog post about Kent Beck’s four rules of simple design, which I think could be improved upon (and, which can lead programmers down the wrong path at times):

Kent’s rules, from Extreme Programming Explained are:

  • Runs all the tests
  • Has no duplicated logic. Be wary of hidden duplication like parallel class hierarchies
  • States every intention important to the programmer
  • Has the fewest possible classes and methods

In my experience, these don’t quite serve the needs of software design. My four rules might be that a well-designed system:

  • is well-covered by passing tests.
  • has no abstractions not directly needed by the program.
  • has unambiguous behavior.
  • requires the fewest number of concepts.

To me, these flow from what we do with software.

The Frightening State of Security Around NPM Package Management

July 10, 2019

I take GitHub’s new security vulnerability notifications seriously, and try to patch my apps whenever something comes up. I recently had trouble doing so for a JavaScript dependency, and uncovered just how utterly complex management of NPM modules is, and how difficult it must be to manage vulnerable packages. And I’m left wanting. I’m also left more concerned than ever that the excessive use of the NPM ecosystem is risky and dangerous.

Coding without (many) Expressions

June 29, 2019

In the imagined Timeline Programming Language, there are some unusual restrictions on the type of code you can write. I thought might be worth seeing if they can help us with real code. I find that when you apply constraints to your work, you often get forced into novel solutions, and occasionally even superior ones. So let’s take Timeline’s restrictions on expressions. In Timeline, you cannot have a compound or nested expression, and the only thing you can do with an expression is assign it to a variable. You cannot use them in control structures, return statements, or method invocations.

Brustalist Web Design Dark Mode

May 23, 2019

Brutalist Web Design Guidelines now support dark mode! If you are using a system that supports dark mode (e.g. MacOS) then the site will show you a different theme with less sun-blasting white background (see image below). I’m viewing this as an accessibility issue, so right in line with the ethos of Brutalist Web Design. Some users need a darker theme or want to have a less bright experience on their computer.

This is likely only supported in Safari on later MacOS, but it’s activated by the media query prefers-color-scheme: dark. Since the site uses Tachyons, I chose to override Tachyons’ color styles rather than create meta styles like “background” and “text color”.

@media (prefers-color-scheme: dark) {
  .bg-near-black { background-color: #eeeeee; }
  .bg-near-white { background-color: #111111; }
  .black { color: #ffffff; }
  .dark-gray { color: #CCCCCC; }

  /* and so forth... */
Rendering of brutalist-web.design's website in dark mode and light mode side-by-side
brutalist-web.design in both modes

Agile Web Development with Rails 6 in Beta

April 30, 2019

I’m speaking at RailsConf, and the beta of the next verison of the seminal Agile Web Development with Rails is now out in beta.

My contribution thusfar was a chapter on ActionMailbox and ActionText, which I enjoyed learning about and would likely use on a new Rails app if I were building it today. If you want a great intro to Rails, buy this book!