Swagger => OADF: Insider View

I still don’t get it. After multiple clarifications with a friend about the recent donation of the what-once-was-only-Swagger API description format to the OAI (Open API Initiative), I’m still confused as to why the contribution of the impartial format without what would be very one-sided contributions of tooling around the format is not the safest step to getting a long-term standard for everyone to benefit from into the public domain. I argue, it is, even if we don’t know how it will turn out.

Not at the cool kids table, what do I know?

I get that some people are feeling confusion, frustration, shock, and even disgust. I also hear people expressing relief, clarity, gratefulness, and vision. The world has far fewer thought-leaders and way more people who want standards they can build cool shit with, make some money and some good happen, and ultimately go home knowing things will generally work as designed again tomorrow.

I’m about to state some things, job whatever. I had no say in the way any of this played out, but we need someone to clarify that the insides of my corporate office is filled with good, fair, and driven people. This is not an evil empire, unlike some other soft competitors, this is where I work. Respectfulness and honesty are two of the Apache Way tenants, two that ring true for me and those I work with.

What are the facts IMO?

Fact: Certain entities owned the rights to the Swagger technology and brand, which for better or worse started as a format plus a cool name mingled together. It eventually became so useful that the format was open-sourced. Later, a company was able to navigate the financial and political mess that has been the API description format landscape for years, producing an API ecosystem standard as significant to real implementers as other open standards like HTTP, JPEG, and . Still, the brand has monetary value but the spec has much broader universal value, and so the spec was donated.

Fact: No one could “sell” the Swagger format is because it was already open source, and though the brand was still legal property, it has been managed with no misinformation or clandestine story behind it. When technology becomes part of a commons, it no longer makes sense to have one brand dominate the tooling and the vendor ecosystem. A separation of the format and the brand was necessary. To convolute the new OADF (Open API Description Format) by including tools that specific vendors donated but not including others would have been even worse an idea than not separating out the format from the brand, and persisting to do so doesn’t prevent these tools from being just as useful and successful as they were before the OAI changes.

Fact: People that truly helped the Swagger ecosystem get to where it is today deserve due credit for what they have done. Their contributions continue to be pivotal to the OADF because without a community, big companies that are already strong-arming the media with boku marketing budgets and completely horse shit press releases will take the OAI over and rule the connected world, one bad choice at a time. The community must maintain leadership in the OAI, and if there’s no room at that table for proven thought-leaders who have already spent years improving and evangelizing the importance of a format like Swagger, then shame on those who say they are leaders but are to busy making ends meet to ask for the right kind of help or spearhead truly pivotal contributions to the open web.

Fact: SPDY was a great start to fixing something, and I liken the work done at Google with the help of the whole industry to elevate much of the great ideas there into the formal HTTP 2.0 spec. Same with WebRTC, if only we could get proprietary chipset manufacturers to be adults and ship more than one optimized instruction set for video decoding on their silicon communion wafers. Much like the SPDY-to-HTTP2 evolution, the need for a standard API description format is long overdue, the OADF being a necessary leap forward which should have happened years ago.

What are we left with in the OADF?

I admire people who stand up for what they feel is right and who are vocal about what happens when things don’t go the way they expected them to. A brand is monetarily valuable, search and replace on the internet is not possible (I get that), and decision-makers usually make the decisions they are hired to make. That’s just how that works.

In the meantime, we have a standard open API description format now, frankly better than all the rest of them, and we can build on it just like all the other foundational technology that makes up the connected world we live in today. Brands are bullshit anyway. It’s the meaning of the thing behind the name that matters.

Peace, love, and internet for everyone.

Iteration, Maths, and Continuous Delivery

Recently I’ve been reading “Godel, Escher, Bach: An Eternal Golden Braid“. I also love to stare at trees, and this morning while waiting for the train, something occurred to me: “What is a tree without time?”

I’ll get to computer stuff in a bit, but follow me for a minute here.

Things take time to develop

We live in a multi-dimensional universe, and one of those dimensions we perceive as the passing of time. Strangely for its inhabitants, time appears to only go in one direction. Concurrently, iteration seems to have a “direction” as well. Just as with a single-dimensional line, you can iterate forwards and backwards. Time’s arrow shows us that’s how it works for us. The concept of “direction” in iterates is also well understood, but there seems to me to be an obvious correlation between time’s direction and iteration.

Back to the tree. My point is that the branches are just iterations of a simple instruction set. They look different, but it’s just a mixture of randomness and iteration. Like this picture of a hair.

A rendering of an iterative algorithm resulting in a shape that looks like a curly strand of human hair.

Watch the video below, but please come back and read the rest of my ramblings after you see this guy reproduce what looks like hair follicles in less than 10 lines of code:

Give me something really WILD to ponder

Warning => Conjecture: I am not a scholar, just a really interested party.

Also, this sentence is not true.

Nowhere in the universe we perceive exists an example of the opposite of iteration (let’s call that idea “statics”). We know that all physical things are part of spacetime. Quantum “jitters” show that even bodies at rest are not truly at rest. Empty space is never truly empty, virtual particles pop in and out of existence constantly. Could this just be way of spacetime alleviating itself of the need to iterate the physical dimensions to keep balance with the arrows in what we perceive to be non-physical dimensions? Or possibly how fractional geometry approaches the Euclidian sticky points in our perceptive capabilities, by iterating continuously ad infinitum? Boom.

How does a book about hair styles help me with a DevOps strategy?

“An Eternal Golden Braid” makes you think, hard. In most cases, that’s a good enough reason for me to read something. And I hate reading, but I love learning. That’s my opinion, go make your own up.

A key concept to keep in mind if you read this book is how entangled things get once you start asking very granular questions about relationships between the observable universe and mathematics (maths), maths and a definition of the self, and how far we can reduce a concept before it satisfactorily models the phenomena we uncover with math, science, and philosophy.

Iteration is present in maths, starting with the concept of zero, something it took us a long time as humans to identify. Take none, add one. Keep doing that until you reach infinity. Presto! Thanks to the simple concept of iteration, when mixed with literally nothing (zero), exposes the concept of infinity.

“DevOps” is an amalgamate term now, involved in everything from rapid iteration to deployment methodologies, distributed systems architecture to “soft” skills amongst team members. It’s all tangled up, which is not a bad thing necessarily. We need cross-disciplinary thought to help expand on how the practices we implement fit together, complement each other, and even conclude something which only causes problems and needs to be excused permanently (think M$ DCOM, Clippy, and maybe even gun control). I don’t like any of them.

How does this relate to continuous delivery?

I am a man who prefers science whenever possible, but I’ll settle for less than scientific if it has promise and until it is disproven. A few taking point came to me this week:

  • Fractional iterates lead to the concept of continuous parameters. Continuous parameters, isn’t that the software we’re building? Or is it us, the people AND the product? This sounds like some of the thinking we have around continuous delivery, loops of deployment and redesign.
  • Any time infinity walks in the room, everything goes to hell and no one likes a know-it-all at a party. Paradoxes abound. The concept of continuous delivery seems a bit like Dante’s seventh circle to me, in that nothing ever ends, it just goes on and on.
  • Like spacetime, the patterns we use and the goals we want to reach are not separable. Better practices lead to better results.
  • Like every tree, every good idea takes time, iteration, and a bit of [pseudo]randomness to develop into something great.

Use whatever processes, tools, and timeframes you need to, but exploring the philosophical underpinnings of continuous systems is kind of necessary if you want to do things better over time.

Can you give me something more practical so I can go home now?

Okay, sure. Here are a few things I’d do if I was a development or a product owner with a team of pangalactically skilled people on my team:

  • Have everyone read this book, or at least this MIT lecture video series on the book
  • Allow members of your team one day a month to play with any idea they want to, the sole purpose being that it is a test of how they manage themselves and accomplish personal goals
  • Iterate over the design of your processes, not just the design of your software; anything that’s working well, f*ck with it. Anything that’s not working well, replace it with something better.
  • Assign one person per week to be an agent of change by asking them to cross-train with other members of your team on one or two things they don’t know about. As the Joker famously said, “Introduce a little anarchy”, which I have seen work very well to upset the status quo in practice.

Good luck. Let me know how it goes.

Zen Thoughts on New SDLC Diagram

The other day I was working on updating my visuals to describe the systems delivery lifecycle (SDLC) for software. Three new depictions arose.


Why does the SDLC need a better visual?

I’m doing this because I’ve never been afraid of change, and the visuals still in use today depicting the phases of delivery are disturbingly incorrect to the modern lifecycle. Take for instance a few common illustrations:


Waterfall, cyclical, even the dreaded CI eternity symbol, all crap as far as I’m concerned. The linear fallacy is just too much to bear.

So I got to work on the whiteboard, to play around with some ideas. I really tried to stick to the “design, build, test, deploy, manage, monitor” phase reductions to simplify my life before round 2 coffee.

Is the SDLC Just a Fractal?

The idea that even a man-made structure like wire transmissions* could elicit fractal patterns just like nature got me thinking about other man-made structures…software and processes…are there fractals in what we accomplish, despite our incredibly synthetic rules and predisposition for straight lines? I’ve always loved this painting:

Fractals have changed my thinking about perceived complexity as a result of a simpler algorithm. There are fractals in all of us, our heartbeat graphed out show how nature may just be surface complexity to our perceived reality.

So I drew out the ‘waterfall’ (yes, pun intended) like a Kanagawa painting:

* Reference to ‘Hunting the Hidden Dimensions‘ documentary on Mandelbrot’s early work at IBM related to SNR telephone clarification algorithms.

If you haven’t read ‘An Eternal Golden Braid‘, at least watch a few moments of the following video, I implore you.

So this works well for categorizing the levels of detail that a large-scale operation like rolling a new idea out into the market requires, but there’s no link to the continuous aspects of the process. Next.

How Is the SDLC Like Digital Public Transit?

After going back to the ‘wheel’ mentality, I realized that there are just some parts of the SDLC that don’t always connect to each other, or at least not every time you complete a full cycle. Things like ‘build’ in a TDD shop do not block ‘testing’, so forcing everyone to go through the ‘build’ phase is wrong.

If instead we were to write out each ‘phase’ of the SDLC in clockwise fashion in a circle, then draw directed vertices, we’d get something like a subway map, like this:


So that’s interesting, certainly more palatable than the fractal illustration for most people, and shows a bit of symmetry, even if just as a shallow concept. The thing I like the best about this one is that you begin to see logical byproducts result from visualizing the paths through this state diagram.

If you draw a line from right before ‘design’ until right after ‘test’, you’d see how the three design/build/test phases that traditionally developers would do and operations wouldn’t touch are separate from the deploy/manage/monitor phases, which mirrors how proficiency in either (but not both) roles usually decides which set of phases you’ll be spending most of your time on as a member of a ‘DevOps’ team, either primarily a developer or an operations person.

Does the SDLC Need Some Taoist Whoop-Ass?

Then things got really weird. I realized that the closer each of the phases are depicted to one another, the easier it was for me to keep in mind that it was possible (sometimes fortuitous) to jump from phase to phase as organically happens in real DevOps / agile teams.

Instead of putting the elaborations (curls, paths) on the outside of the continuous structure (circle), they should be inside it. At first I drew it like a ’69’ which I later remembered has cultural connotations that are best avoided. Flipping it around, only later when I was out to coffee with some co-workers did someone point out that it looks like the Taoist Taijitu (paisley) symbol. That endeared it to me further:


(From top-right in clock-wise order: design, build, test, deploy, manage, monitor)

Any time I can work in some pseudo-science or eastern philosophy into a technical topic, the added mystical sense is a bonus as far as I’m concerned. You come off looking all cool and a bit nuts at the same time.

Further Detail on Why I Don’t Like Existing SDLC Paradigms

Formally, my problems with established paradigms for how to visualize the SDLC are:

  • The left-to-right approach as a one-direction trip is inaccurate to how effective people work together, not separate; there are loopbacks thanks to humans
  • The ‘fix’ to take a waterfall process and just wrap it around on itself to make a continuous process just seems lazy and incomplete
  • Most depictions have no symmetry and no emergence of ‘DevOps’ role separation

People will use what makes sense to them. I will continue to elaborate these ideas until they bore me.