No Shit In The Ranch House

Please forgive my use of a four-letter word. But it is central to my overall point, as I hope you will soon see.

Ranches are shit-management systems. There are other ways to think about a ranch, more refined and polite. But this way of looking at a ranch is useful. A ranch is all about raising animals for food, and animals shit. A proper ranch, unlike the factory farming methods criticized in the new film Eating Animals, handles these goals in a manner that is respectful to the animals in question.

The single biggest problem with having lots of animals in a single location is shit. More animals means more shit.

Properly managed ranches have all kinds of systems in place for managing shit. They design their animal stalls to be easy to shovel. They use wheel-barrows and bobcats and all kinds of reliable solutions to ensure that shit does not pile up in the wrong places.

Cows are willing to defecate in transit. Which means that as cows are herded from one ranch facility to the next, they occasionally make a trail of cow paddy. Cowboy boots are designed to be easy to wipe-down, for this reason. On a ranch, shit tends to get everywhere, and the ranch as a system spends a huge of amount of energy addressing this problem.

My understanding of ranches arise from fond childhood memories and family lore. My great-grandfather was the foreman of the Pfluger Ranch (which would later become Pflugerville). My understanding of a ranch is based mostly on third and second-hand stories, and is likely not too much better anyone else’s. But what limited understanding I have is enough to grasp two basic concepts: First, shit management is an ongoing unpleasant task on a ranch. And second, there is typically a large expansive home at the center of large ranches. This second concept is where we get the reference to a “ranch-style” home, a single-floor phenomenon where there is very little incentive to build a second story.

Now, imagine that you run a grocery. You decide which ranches provide the meat to the butchers in your grocery store. In that role you would have a pretty good idea how ranches are supposed to operate, having seen many of them over the years. You would be familiar with the rituals undertaken upon arriving as a guest at a new ranch. You are invited into the central home, which looks from the outside to be a spacious, welcoming house. This is the reason it is so often referred to as simply, the “Big House”. This is the seat of power in the ranch, and you note that the cowboys/girls that enter with you defer to the significance of the place by removing their hats.

Now further imagine, upon visiting this ranch, that you find a big, heaping pile of shit, in the main parlor of this central house. Right inside the front door. Right on the obviously expensive rug. Inside the house.

This is your first impression of the ranch. What are your thoughts? You might wonder “How did a cow get in here?”, “How long has this shit been here?”, “Why didn’t someone clean this shit up before we got here?”

But from the perspective of your evaluation of the ranch, it does not matter what the answer to any of your questions are. From your perspective, this is not a ranch you want to work with. Because you know that there are lots of moving parts to a ranch, lots of things that need to go well, and if the ranch is so poorly managed that it cannot keep bullshit out of what should be the best-kept part of the ranch, then it is extremely unlikely that the ranch has its shit together anywhere else. (see what I did there?) Most importantly, it is not worth your time to perform the very careful examination of the ranch that would be required to undo your first impression.

That does not mean that you (as the grocer still) would penalize a different ranch for having shit in the stalls, or shit in the barn or shit on a walkway… Dealing with shit, even stepping in shit is part of the life of working on, or even visiting, a ranch. But it really matters where the shit is. And if you see shit in the parlor of a ranch, it will take herculean efforts by the members of that ranch to ever regain your trust. But most importantly, even if the ranch were to undertake those efforts to change your mind, you are just going to go down the street to the ranch that seems like it has its shit together. You simply do not have time for that shit. (it is too easy)

Of course, you think that I have been talking about ranches and shit this whole time, and you would be right in guessing that this is just a metaphor for something else. Something that I, in a non-cow related technical profession, might have more experience with.

What I am really talking about here is software bugs. Bugs = Shit in this analogy and Ranch = Software Project. One way to think about the software development process is that it is all about fixing the bugs that are a natural by product of software features. More features, more bugs. More cows, more shit. Everyone expects the bugs in software, just like everyone expects shit on a ranch.

But if you have shit in the parlor of your ranch house, then it is obvious to anyone who is evaluating your ranch that you are not effectively managing your shit. In the same way, if you have a bug in the instructions that are covered in the of your Github software repo, people are highly unlikely to forgive that.

When a new developer comes across a project on Github, (or Gitlab or Sourceforge or who knows now that Microsoft has bought Github) and that project fails to correctly install, or basically function as the project file in the repo suggests that it will, then that developer will judge that software is useable and will probably never come back. (For those who are not following there is a special file, called, that Github treats as the introduction to your software resource. When you scroll down in the VueJS/Vue project, for instance, when you start scrolling down, you start seeing the main files inside the software project, followed by a web content that is generated by GitHub by interpreting the Markdown contents of the file.

This is the reason why I get so upset that projects that I fund, sponsor, contribute to or rely on have failures in the way that the software should function in the Readme. It means that the maintainers of the project have profoundly forgotten how the process looks from the outside. The team has become so focused on moving forward with new features and functionality that it has forgotten what the experience of a new developer or user reaching out to a new project is.

When a developer of a FOSS software project on github releases a new build of their software, pushing to “master” in git-speak and suggesting that some other version of a software project is acceptable, they need to do a final manual check to ensure that on a new server, with a fresh OS installation, with nothing configured, that following the installation and configuration instructions in the file will work all the way to the “example usage” stage.

I love the new focus on automatic integration. Travis-CI et al have made it much easier to automate final unit testing. Test-driven development is a wonderful idea. But developers still need to do a manual check before a specific release of software to ensure that the current version of the instructions in the Readme, actually result in a good experience for first-time users. Unit tests cannot tell you if the english-language “startup” instructions in the Readme are up to date.

Sometimes, changes in software result in the need to update the Readme instructions. Sometimes the Readme contents are correct, but there is an introduction of a new requirement for the project (new database tables for instance) that need to be automatically detected and fixed on first-time use. I cannot imagine that there will every be an automated system that will predict every new dependency and process change.

I am also not suggesting that every bit of documentation needs to be updated with every release. It is certainly important that documentation generally be maintained and certainly documentation coverage should be considered at a minimum for every release. But while that is important, that is not what I am talking about here. The question that every new user is asking when they download software that solves a problem from Github is “will this thing work for me”, and answering that question frequently requires a huge investment of time and money. But before they make that decision, they want to know “is this software project basically sound?”. If the answer to this question is “yes” then they will make the greater effort to discover if the software works for their use cases.

As long as the new developer believes that the underlying software project is basically sound they will be tolerant or even better, collaborative, with regards to the bugs that they do find. But they want assurances that the software basically does what it says on the Tin. They want to know that the maintainers of the software basically have their shit together, which makes investing in the software a reasonable choice.

Play testing a new software release will always need to be a manual task that is done at the end of sprints. If it is not done then software that is publicly version controlled (on Github or elsewhere) run the risk of alienating new developers which is a death-sentence for any project. If a software sprint ends without “time” to play-test the new release to ensure that it works on fresh systems, then the scope of the sprints needs to be reduced until time for that task is accounted for.

In my opinion, this is the single most important thing that a software project can do to market itself and succeed in market that is crowded with other publicly available Open Source software. It one of the great weapons that modern developers have against the scourge of the “it-works-on-my-machine” disease that all developers seem infected with.

No shit belongs in the ranch house. Try to ensure your Readme “get going” instructions are perfect with every new release.