Practices Icon


Development and business practices, methodologies, workflows, etc.
266 Stories
All Topics Icon

5 tips for making documentation a priority in open source projects

1️⃣ Value contributions to documentation just as much as code contributions
2️⃣ Put documentation and code in the same project repo
3️⃣ Make documentation a requirement for a merge or release milestone
4️⃣ Have a consistent contribution process for code and documentation
5️⃣ Have well-documented processes for contributing to documentation

That’s the TL;DR, but each of these is expanded upon in the article.

John D. Cook

The worst tool for the job

John D. Cook:

I don’t recall where I read this, but someone recommended that if you need a tool, buy the cheapest one you can find. If it’s inadequate, or breaks, or you use it a lot, then buy the best one you can afford.

If you follow this strategy, you’ll sometimes waste a little money by buying a cheap tool before buying a good one. But you won’t waste money buying expensive tools that you rarely use. And you won’t waste money by buying a sequence of incrementally better tools until you finally buy a good one.

What follows is an application of that idea to software tools.


How to write technical posts (so people will read them)

Writing is hard. Technical writing can be even harder. This piece by Sandy Maguire has lots of help in it:

Here’s the biggest thing to keep in mind: your reader doesn’t really care what you have to say. You get maybe four sentences to convince them that your essay is worth their time. If you haven’t made your case by then, you’ve probably lost them to the next tab they binge-opened.


Why we ended up with a centralized logging solution

In the process of moving to our ideal logging system, we constantly discussed the pros and cons of different solutions, and each of us defended the requirement close to them or changed the configuration parameters they needed, asked intriguing questions or sent us back to the original set of requirements.

I love write-ups like this one from the trenches where people share their journey to deciding on a particular solution. Every decision has a context and many blog posts gloss over that, resulting in silver bullet-y hand waving. That’s not super useful when trying to make your own decisions. What is super-useful is being able to understand the circumstances in which others made a choice. That way you can decide if your situation is close enough to theirs to make a similar decision… or not. Icon

Use systemd timers instead of cronjobs

Is it time to migrate away from cron?

Like cron jobs, systemd timers can trigger events—shell scripts and programs—at specified time intervals, such as once a day, on a specific day of the month (perhaps only if it is a Monday), or every 15 minutes during business hours from 8am to 6pm. Timers can also do some things that cron jobs cannot. For example, a timer can trigger a script or program to run a specific amount of time after an event such as boot, startup, completion of a previous task, or even the previous completion of the service unit called by the timer.


LEGO blocks and organ transplants

This post is so brief that I’ll just quote it in its entirety for you:

People have been comparing software components to LEGO blocks for a couple decades. We should be able to assemble applications by snapping together modular components, just like LEGOs. There has been progress, but for the most part we haven’t realized the promise LEGO-style software development.

Integrating two software systems is usually more like performing a heart transplant than snapping together LEGO blocks. It can be done—if there’s a close enough match and the people doing it have enough skill—but the pieces don’t fit together trivially. And failure may not be immediately obvious; it may take a while to see signs of rejection.

Just as true today as it was when John wrote it in 2011.

 Itamar Turner-Trauring

Your dev environment matters less than you think

I knew I was going to nod my head in approval before I even landed on Itamar’s website:

Imagine you’re training to become a chef. You will need to learn how to use a knife correctly, to chop and dice safely and quickly.

And yes, you need a sharp knife. But when you’re starting out, it doesn’t matter which knife you use: just pick something sharp and good enough, and move on. After all, the knife is just a tool.

The people eating the food you cook don’t care about which knife you used: they care how the food tastes and looks.

After six months in the kitchen, you’ll start understanding how you personally use a knife, what cuisines you want to pursue, what techniques you want to vary. And then you’ll have the knowledge to pick a specific knife or knives exactly suited to your needs.

But remember: the people eating your food still won’t care which knife you used.

I’ll just leave this right here.


Validating Kubernetes YAML for best practice and policies

This article compares six static tools to validate and score Kubernetes YAML files for best practices and compliance.

One of the challenges with YAML is that it’s rather hard to express constraints or relationships between manifest files.

What if you wish to check that all images deployed into the cluster are pulled from a trusted registry?

How can you prevent Deployments that don’t have PodDisruptionBudgets from being submitted to the cluster?

Stay SaaSy  Icon Stay SaaSy

Picking your tech stack for dummies (and the future)

From the anonymous writers at Stay SaaSy…

Picking your tech stack in an early stage startup is one of the most important decisions you’ll make. Read on to hear about rules of thumb for making these critical decisions.

Rule 1: When It’s Really Early, Just Use What You Know

If you’re still in prototype, less than 4 developers, do-or-die mode, just use what you know. Unless your product has deep technical requirements the only thing you should optimize for is how fast you personally can code. Don’t try something new. Don’t experiment. Write code.

Kabir Nazir

How to write good Git commit messages

From Kabir Nazir on the AltCampus blog:

One of the things a lot of newbie developers overlook often is the format of their commit messages. Properly formatted commit messages can do so much more than just looking neat…

Use the imperative mood(present tense) when framing messages … Think of each commit in your code as a change that is being applied to your codebase.

Andy Bell

CUBE CSS — Composition Utility Block Exception

Andy Bell recently shared his new CSS methodology oriented towards simplicity and consistency with “a heavy dosage of pragmatism.”

If there’s one thing you can guarantee in tech, it’s that someone, somewhere, will declare that CSS isn’t up to the job of “big projects” and what will undoubtedly be recommended by those same people will be either a JavaScript-heavy approach or some sort of all-in utility class approach like Tailwind.

The problem is, a huge number of projects are websites, so that advice normally doesn’t work for the vast majority of developers. For context, it’s estimated that WordPress powers around 36% of the internet and is still rising. Compare that to a paltry 0.3% of websites that use React, for example. It’s important to keep those figures in mind.

If you’re deep in CSS, you’ll want to read the whole post. Andy goes on to explain the methodology and how he writes CSS, then wraps up saying…

This isn’t a heavily documented, complex methodology. Well, not now, anyway. It’s more of a concept method of organizing CSS just enough to not pull to far away from the “classic” way of writing it. Really, it’s more of a thinking structure.

Y Combinator Icon Y Combinator

How does your company manage its encryption keys?

This was a great question asked this week on Hacker News – 232 comments and counting…

We just had an interesting data loss at work, that was due to data being encrypted at rest. We somehow managed to delete the encryption keys (still figuring out how), which became an obvious problem once our main database instance was rebooted.

Luckily we were able to restore the data, but now I (we) really want to learn what a proper setup would look like.

Balthazar Rouberol

Shell productivity tips and tricks

This post is part of a sample chapter from Essential Tools and Practices for the Aspiring Software Developer — a self-published in-progress book by Balthazar Rouberol and Etienne Brodu.

I estimate that I spend around 50% of my day working in my text editor and my terminal. Any way I can get more productive in these environments has a direct and measurable impact on my daily productivity as a whole.

If you spend a good chunk of your day repeatedly hitting the left and right arrow keys to navigate in long commands or correct typos, or hitting the up or down arrow keys to navigate your command history, this chapter should help you get more done quicker. We will cover some shell features you can leverage to make your shell do more of the work for you.

On a personal level, I probably use some of these up to 30 times a day, sometimes even without thinking about it, and it gives me a real sense of ownership of my tool.

Drew Devault

How to store data forever

It’s certainly interesting to ponder how to store data for as long as you possibly can, which Drew highlights very well. But I really enjoyed the questions at the end on “actually storing data forever”…

Let’s say you’ve managed to keep your data around. But will you still know how to interpret that data in the future? Is it in a file format which requires specialized software to use? Will that software still be relevant in the future? Is that software open-source, so you can update it yourself? Will it still compile and run correctly on newer operating systems and hardware? Will the storage medium still be compatible with new computers?

0:00 / 0:00