Things That Matter Most

Things That Matter Most

Iterative Improvement

by

The first time I sat down to write a book, things went horribly. I tried to piece together an entire story in my head and write it down, from start to finish, all at once. I kept up the charade for a month or so, then burned myself out and gave up part way through.

The second time, I didn’t plan anything out and wrote an entire story from start to finish in three weeks. It was a complete story, but rambles at parts and loses its ability to make any sort of sense less than a quarter of the way in.

This third time, I carefully planned out components and broke the larger narrative into smaller stories. Each of the smaller components stood on its own and could be written, polished, and rewritten independently. Subsequent stories added to the overall narrative and enhanced the feel of each. It was the first time I felt I’d been successful, and it gave me a great sense of pride to be finished with something worthwhile.

It also gave me a new perspective on modular development in software.

Decoupled Development

The failing of test driven development is that it requires you to have a well-thought-out architecture in mind before you ever begin writing real code. If you’re following a traditional “waterfall” development method, this is fairly straight forward. Unfortunately it also means your entire application must be completely planned out and documented before you can write tests. As such, you risk death by documentation and are better suited for a different paradigm.

Instead, I would encourage you use test informed development. As you build each component, write tests for that component at the same time. Your tests serve as further functional documentation for your new code and, honestly, no one will know the difference if you commit both at the same time.

Fundamentally, though, your application should always be broken up into separate components – each should be capable of functioning somewhat on its own. The independent functionality makes for better, more decoupled unit testing. It also make for easy substitution when a newer component is available. Finally, independent modularization means you can partition out development of the larger project to disparate teams.

Unlike the waterfall method, completion of each independent component can be demonstrated to stakeholders before shipping. Under a waterfall scheme, you often must wait for larger milestones before an incremental demonstration can be made – with this more agile scheme you can demo each component independently.

It powers more iterative improvements on your product, taking you from planning to MVP in no time.

Often times, the projects I try to build are too much like that first book – or like the car in the first example above. I have a grand idea, and I build tiny pieces that don’t quite do anything on their own. I end up failing around step 3 and never ship a final product because I never reached a stage at which my product was usable.

The second example fits a more refined and productive development pattern. The wheels built in step 1 might not power a car, but they provide a model essential for building wheels to come – and still help power a minimally useful first release. Iterative improvements beyond add new functionality; again, iteratively adding components that still create a functional intermediate product.

Break development apart and you’re left with components that function on their own, components that can be tested/replaced/refactored independently, and a working product after each addition of a new component. It’s a wonder we don’t run all development this way.

Death by Documentation

by

Before I finally made it to a more modern company that fully embraced Agile methodologies, I worked for a firm that used the waterfall method exclusively for project planning.

It was a nightmare.

The Background

I was working for a small firm that had become fairly well-established in its industry. We focused on building clinical management and diabetes monitoring software for both clinicians and patients. Our products were making a real difference in the world, so coming to work every day actually felt important.

Unfortunately, we moved too slowly to do anything substantial.

Our flagship product was coded in Turbo Pascal. It was a robust clinical product, but the age of the codebase meant our primary quality assurance tester was stuck on Windows 98 – most of the tools we used hadn’t been maintained beyond that. I was actually hired as part of an initiative to update our product offering and take the desktop-based application online.

Over my time with this company I was able to add several API layers that allowed clinics to communicate with one another. I also engineered a cross-browser, cross-platform, JavaScript-based blood glucose meter download interface to help move us away from an Internet Explorer/Active-X dependency.

But I never did mange to help launch new web-based projects. There’s a very good reason for that, too.

Waterfall Development

The idea of waterfall development is that you start with a plan – a comprehensive plan for building out the project. Unlike agile development, where the team meets frequently and can pivot quickly when new information is uncovered, the waterfall method means you start with a comprehensive spec and, often, work to meet the spec without coordinating with the rest of the team.

At least not that frequently.

Our system started with a client request for a feature. That feature was then fully documented and the ideal implementation roughed out in the planning document. We’d then pass a complete specifications document to an engineer – sometimes they were in-house, sometimes they were outsourced. The engineer would implement the feature, then the new code (and the original spec) were shipped back to the QA tester for verification and acceptance.

It worked, in a way. It was incredibly slow, though, and more complex feature requests (like the rewrite of our Pascal app into something that would work for the web) were lost under a mountain of documentation.

My last project at the company took three months to document. It was a dashboard-style application for tracking and reporting on information like HbA1c, BMI, Cholesterol, and other vital health statistics. We had color coding, interactive reports, automated coordination with clinical management systems. It was a robust application.

It was detailed in an 18-page specifications document that, as I already mentioned, took almost three months to prepare and perfect.

Our requirement before we could even start development was to have a fully-fleshed out specifications document. Unfortunately the overall project and final document were so detailed, that the project was shelved rather than shipped. Our focus on documentation killed any hope of ever moving to development.

How are projects at your company planned out? Do you start with clearly-defined overall goals and discuss momentum frequently to keep development on track while still allowing for agile shifts in day-to-day direction? Or do you start with a rigid specification that squelches creativity and dooms projects to fail if any underlying assumptions prove wrong in the future?

Beautiful Code

by

I don’t always write the best code. I write code that runs, passes tests, and solves the business problem. Unfortunately this also means it’s often code I come back to in a month or so and want to scrap to completely rewrite.

That said, I never want to refactor code just for the sake of refactoring code.

I want to rewrite my code because it’s ugly. It’s not poetry. It’s not art. It’s not even worthy of being used as an example slide in a presentation or a blurry screenshot in an article. It’s that code you use as an example of what not to do.

And it ships in finished products.

The Battle Between Beauty and Shipability

Sometimes we have to make the tough call and label code as “good enough” so we can get it out the door. This is a necessary evil of shipping a final project, but it also sacrifices inspiration and innovation. Beautiful code, like any form of beautiful art, takes time to develop and get right.

I once met a poet who spent a year writing a 15-line poem. A year.

I asked why it took so long. “It didn’t feel right.”

His job wasn’t just to write fifteen lines of text. It wasn’t to fill the page with words that looked nice together. His job was to convey human emotion – to paint a picture with symbols and images that felt universal and personalized at the same time.

He did an effective job, and that tiny poem won him plenty of awards over the length of his career. It actually paid, in the end, far more than any fifteen lines of text have ever come close to paying in mine.

We constantly walk the line between writing code that ships or functions and code we can be proud of. It feels a bit disingenuous to say we’re on the verge of “software craftsmanship” when I have yet to meet a developer who hasn’t apologized for the state of their code before letting a colleague take a look at it.

A carpenter doesn’t apologize for their table before showing it off to a customer. A painter doesn’t apologize for their landscape before a showing. A writer doesn’t apologize for the poor diction in their novel on the inside of dust jacket.

We shouldn’t be apologizing for our code before showing it off. We should be focusing on making our code both functional and something to be proud of. We should focus on shipping not at the expense of beauty in our code, but because we’ve built beautiful code.

Blaise Pascal has been quoted as once saying, “I would have written a shorter letter, but I did not have the time.” Writing a short, elegant, beautiful letter takes time. But the letters given that time are treasured for generations.

Writing short, concise, beautiful code takes time. One day, though, we might actually write code that will likewise be treasured.

Open Sourcing Awesomeness

by

No one ever wants to go back and look at their old code. If you’re worth anything as an engineer, it means you’re always learning, always improving, and writing progressively better code as you learn and improve.

Often it’s easier to just start over than go back and refactor, so if a chunk of code isn’t actually broken, we leave it alone.

This usually sets new, self-taught developers up for failure. I learn by looking at what others do, internalizing it, and reapplying past successful practice to new engineering problems. I learned to code JavaScript by looking at the auto-generated snippets from Dreamweaver. 1 I learned PHP by looking at WordPress code.

Most of my early patches were rejected from core based on abysmal standards adherence. I’d write a patch following documented WordPress standards, only to have it rejected because it didn’t fit within the legacy class or set of functions I was patching. I’d write another patch following the standards and style implied by the code in the file I was patching, only to have it rejected because it didn’t follow documented standards.

The discrepancy made it very difficult for me to understand what was going on. My first year or so of contributions to WordPress came in the form of forum threads and plugins because “doing it the WordPress way” was just too damn hard.

Premium Engineering

I pride myself now on working with some of the best WordPress engineers in the world. At 10up, our clients know they’re getting solid editorial projects backed by even more solid engineering. There’s some magic in that, but most of it is learned.

Over the past months, I’ve worked hard with a couple of other engineers at 10up to heavily document our engineering best practices – the tips and tools and workflows we use to pull together cutting-edge projects for our clients. We covered everything from version control to dependency management to language-specific coding patterns – and were able to shore up a lot of our own internal communication at the same time. 2

This week, we’ve open sourced our best practices document.

This document serves as a glimpse into how we do WordPress at 10up. It’s a fairly detailed set of documents that, like the code it influences, is constantly getting better as we continue to learn and improve. As a public document, it’s also open to collaboration – feel free to provide whatever feedback you think is necessary.

My hope is this document becomes a solid resource for the community. Hopefully the next developer can get started right away rather than spending a year learning the ropes on her own like I had to …

Notes:

  1. Yes, my early JavaScript code was horrendous! ↩
  2. Some of the things we pulled together in documentation was just assumed to be the standard by most, but was still a complete mystery to others. Making sure it’s all documented in one place is a great way to educate new engineers, as well as help established developers keep an eye on their craft. ↩

If you’re not part of the solution …

by

Other developers often criticize me for making suggestions about WordPress core.

The point out on Twitter than I’m contributing ideas without taking the time to contribute code suggestions. The point out that I’m posting to Twitter and my personal blog topics that would be a better fit for Trac or the WP Hackers mailing list.

Sometimes the comments on this site take on a snarky attitude of “well, then why don’t you do it?”

I have my reasons.

Starting with a Blog

Sometimes my ideas are just that, ideas.

I have ideas often on just about everything. Some of the ideas are useful, some are just things that would make life easier for me and no one else. Before I sink hours of coding time into fleshing out a patch, I want to get some validation around the idea.

The number of times I’ve written a patch or a plugin or spec’ed (and built) out a feature, only to have WordPress core take a different direction or to have the community decide that the feature is niche enough to not belong in core in the first place …

It burns a developer out to constantly work on projects for the community only to have the community decide not to use those projects. As a result, I don’t want to pursue one of my ideas beyond the concept stage unless there’s support in the community for that feature’s development.

I’ll post the idea here to start a discussion. Trac is inappropriate for such a discussion of proposed features since it’s our active development site. WP Hackers is … basically a waste of time at the moment. 1

Struggling to Contribute

I work with WordPress daily. I write code that powers millions of websites and I contribute code to themes and plugins used by scores of millions of people on the Internet daily. At the same time, I don’t always feel that there’s a concerted direction for my contributions.

My schedule is such that I can’t commit to leading any specific features. My contributions to feature teams come in spurts when I have a few moments of downtime, or when a feature (or lack thereof) directly affects a client and I can use daytime coding hours to hack on core and prepare a fix.

As a frequent user of WordPress, I often see a lot of the problems my fellow users face – I struggle at times, though, to find a way to contribute to fixing those problems. I see documenting proposed fixes, features, suggestions, and critiques as my way of contributing when I can.

Am I part of the solution? Or am I just conflating the problem even further?

Notes:

  1. I strongly believe we should invest significant time into reclaiming WP Hackers as a serious core hacking mailing list. Right now, it’s not a constructive community and while I still subscribe to the list, I read it perhaps once a month and haven’t posted to it in ages. ↩

Magic of Collaboration

by

About a month ago, a colleague silently added me as an administrator to a GitHub repository.  I took a look and saw a bunch of code and lingo without much explanation.

Scratching my head I decided to ignore it for a while and let him do his thing.

Then, a couple of weeks ago, another coworker was talking about code related to the project in the company chat room.  It happened to deal with a field I know and love, so I paid a bit more attention.

We talked about features, load balancing, threading, and remote API integrations – all things I love and enjoy.

The conversation had me super excited about this product my team was building – a project I now had a hand in developing – but I couldn’t tell anyone about it yet.

The anticipation was excruciating!

Enter PushUp

We finally pushed our new product out the door yesterday afternoon.  If you missed the announcement, feel free to wander over to our company blog to catch up.  The video is totally worth it.

I’m super excited to announce that I’m using 10up’s newest product on this site, too – if you’re visiting on Safari you’ve already see the popup asking for permission to notify you.

Please say yes.

Part of a Team

Working remotely can be difficult.  You’re isolated, don’t spend much time talking to team members, and generally feel like you have to go it alone on projects.

At 10up, that’s not the case.

I work with a (growing) group of high-class, high-talent, brilliant developers and strategists. 1  We work on amazing projects for clients and tackle every obstacle in our path as a group.  As of yesterday, we also work on and publish incredible products in the tech space.

A fact that excites me about the future of development and the future of 10up.

My team works on spectacular projects – and we never work on these projects in isolation.  I’m proud of what we’ve accomplished together and excited about what we’ll do next.

Notes:

  1. And did I mention, we’re hiring!  If you have what it takes to be a contributor to a team of high-caliber developers, strategists, and all-around technologists, drop me a line and I’ll make an introduction! ↩