The resume format

While the means of initial filtering drastically changed (from a manual review by a competent human to automatic parsing by software), the format has not changed at all and, worst still, there’s no universally adhered standard to use for the parsing/data extraction process.

Let’s break this problem down to its core components:

The format is very loose and clearly aims to accommodate human thought and analysis patterns, not those of computer algorithms.

When I say the format is “loose”, I am referring to the fact that, while there’s an abundance of (sometimes contradicting) guidelines, there’s no standard. In particular (and this is important for automated parsing), there’s no unified layout and there are several different common file formats, each with its own sub-formats.

PDF (Portable Document Format) is one such common “format”. Here’s a short blurb from Wikipedia:

PDF files may contain a variety of content besides flat text and graphics including logical structuring elements, interactive elements such as annotations and form-fields, layers, rich media (including video content), three-dimensional objects using U3D or PRC, and various other data formats.

My own resume is a PDF generated using Latex, from a template I found in this Git repo. I am also a co-maintainer on mdtopdf - a project that produces PDFs from Markdown.

PDFs are easy to produce and look good to the human eye and, as Wikipedia puts it, PDF is a file format developed by Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software”. The “independent of application software” bit is rather important because it means I do not have to use MS Word (by the way, there are several, very different, MS Word formats, since not all versions use the same format by default) or, more relevant to my case (since I use Linux exclusively on all my personal equipment), LibreOffice (in the hope that it will look okay on whatever MS Word version the recruiter opens it with).

Let’s focus on this bit from the last paragraph: look good to the human eye.

Allow me to regale you with a short quote I encountered in The FORTRAN colouring book by Dr. Roger Emanuel Kaufman:

Before you try to solve a problem using a computer, it’s only fair that I tell you a few things about what computers are like.

Once knew a fellow who called up a computer dating service, Whey tried to fix him up with an IBM machine. Needless to say, it didn’t work out, He was witty, handsome, a dashing bon vivant raconteur - terribly debonair. The computer was dumb, unimaginative, totally lacking in creativity. He spoke fluent Francais - the machine only understood FORTRAN. The poor computer couldn’t follow his exuberant dialogue - it could comprehend only the simplest of grammatical constructions, of course, it didn’t work out. For one thing, the computer was a lousy cha cha dancer. For another thing, there was a difference of religion. The computer thought it was God and he was upset about how they’d raise the children.

To be fair, we should recognize that computers have many good points as well, true, they are basically stupid. However, they have Great memories, they are incredibly fast, they are terrific typists, and they make good money, last but not least, Zey vill follow inztrukshuns to zee letter!

This book was published in 1978. We’ve made loads of technological advancements since but the general message remains very true today (and those who go “I built software with chatGPT without learning how to code” or “Soon developers will be made obsolete” will be well advised to read it).

The takeaway is simple: machines and humans are very different in how they interpret/process data. One salient point to understand is this: machines do not think, they compute, which is why they are called computers, not “thinkers”, it’s all in the name.

Parsing a PDF (or DOCX or other common formats, for that matter) resume, intended for the human mind is quite a complex task for a computer. Before we go on, let’s define parsing in this context:

In computer science, parsing is the process used to analyze and interpret the syntax of a text or program to extract relevant information.

Humans can do this easily and intuitively. Machines can be trained to parse resumes written with humans in mind but it takes an effort and is very error-prone. As I reckon many non-programmers are aware, machines ultimately deal with binary sequences (0s and 1s - bit on, bit off - if it makes you think of Karate Kid, we think alike:)). They can be taught to transform/represent a large variety of data pieces into/in these sequences but some formats make it far easier than others.

When writing software, one will never opt to store/pass data in the form of a PDF. Over the years, we’ve come up with an abundance of formats that are a compromise between what humans and machines “understand” best (in quotes because machines don’t really understand anything, they compute and process).

If you’re interested, you can look up a few common ones: XML, INI, JSON, YAML; there are, of course, many more.

Let’s use JSON for illustration purposes. It’s a reasonable choice as it’s one of the most popular ones, certainly when it comes to APIs (Application Programming Interface). Similar to HTTP, even if you’ve no idea what the term means, I assure you that you make use of APIs on a daily basis. Educating people on these concepts is a laudable aspiration but as it’s not the purpose of this particular series, I’d suggest looking that term up, rather than cover it in this text. JSON handles nested hierarchies well and we need that to represent a person’s resume.

If I wanted to format the data in my resume as a JSON, it would look something like this:

{
  "name": "Jesse Portnoy",
  "email": "jesse@packman.io",
  "github_profile": "https://github.com/jessp01",
  "gitlab_profile": "https://gitlab.com/packman.io",
  "personal_site": "http://packman.io",
  "linkedin_profile": "https://www.linkedin.com/in/jesse-portnoy-4921752",
  "title": "Multidisciplinary Programmer, Builder & Packager, Automation Engineer",
  "skills": {
    "programming": [
      "C",
      "PHP",
      "Perl",
      "JavaScript/NodeJS",
      "Dart/Flutter",
      "BASH",
      "Go",
      "SQL",
      "Ruby",
      "Python",
      "C#",
      "Java"
    ],
    "devops": [
      "LAMP",
      "Nginx",
      "AWS",
      "Google Cloud Platform",
      "Docker",
      "Vagrant",
      "Travis CI",
      "GH Actions",
      "Ansible",
      "Chef",
      "Nagios",
      "Prometheus"
    ]
  },
  "experience": [
    {
      "company": "Sirius Open Source Inc",
      "start_time": "2023-09-18T09:00:00Z",
      "end_time": "2024-10-01T17:00:00Z",
      "title": "Senior Developer",
      "description": "Things I did go here"
    },
    {
      "company": "Kaltura",
      "start_time": "2012-02-01T09:00:00Z",
      "end_time": "2023-03-31T17:00:00Z",
      "title": "Senior Developer",
      "description": "Things I did go here"
    }
  ]
}

The above is of course, truncated but you get the point. See what I mean by a compromise between what humans and machines “understand”? Most humans would definitely rather read the PDF but they could still read the data when formatted this way and it would make sense to them; computers have no preferences (as much as I love them, I make an effort not to humanise computers, I think it’s important) but parsing this JSON will be faster and less error-prone for them (though, not as fast as a binary sequence).

At this point, you may be thinking:

Okay, I got it, machines and humans process things differently and some formats are better suited for one rather than the other but surely, you don’t expect Salesman Smith and Solicitor Jones to manually format their resume this way to aid computers! I mean, they’re meant to be aiding us!

To which I say: NO, I do not expect any human to manually format their resume as a JSON. In fact, I don’t want to do it either; while I can do that (and it’s not that hard), there’s no reason for anyone (programmer or not) to struggle with finding a missing ,, : or [] in the above JSON. Instead, we should:

• Agree on a standard (any standard, even a very flawed one, is better than no standard at all and standards evolve, to address needs)
• Write software that takes input in the manner humans are used to and automatically transforms it into such a JSON (or YAML, or whatever, really - something a computer does not have to work hard to parse - and remember, it’s not just about how hard it works, it’s also about how likely it is to make a mistake)

Trust me, it’s very easy. Recruitment software is largely a proprietary/close source industry (which is part of the problem, actually) but I was able to find a project called open-resume. open-resume is FOSS (licensed under AGPLv3, written mostly in TypeScript) and it provides two main functionalities:

• Parsing existing PDFs (https://www.open-resume.com/resume-parser)
• Producing PDFs from inputs provided in an HTML form (https://www.open-resume.com/resume-builder)

The latter functionality can easily be extended to produce, alongside the PDF, a JSON similar to the one in my example above.

If we all agreed on a standard, people could easily generate and submit both files when applying for a job, making it much easier for all involved.

The format aside, there’s another important point to consider: if you consult any resume “expert” (and there are plenty of those) or perform an online scan of yours, they will all tell you that a resume must be two pages max (and some will even say it must be under 800 words long). This is very restrictive, especially when it comes to roles where so much emphasis is put on one’s technical experience and level of expertise with given technologies (programming languages, frameworks, platforms, etc) and considering the overwhelming abundance of these. Going back to the quote from The FORTRAN Colouring book

we should recognise that computers have many good points as well. True, they are basically stupid - however, they have great memories, they are incredibly fast

To a human, each additional page translates to several minutes of processing time (hence why this limitation was introduced in the first place) but to a machine, it’s utterly negligible, especially with the resources we have at our disposal today (the computing power on your phone alone is far greater than what the machines that send people up to space in 1969 had). It reminds me of a story I heard, about a bureaucratic department where a paper form had to be filled with blue ink. When someone finally questioned it, they found that this regulation was established because the machine used for scanning said form had difficulties with other ink colours. That machine was made obsolete decades prior and the new processing method did not have these limitations. Something to think about.

This feels like a good stopping point.

In this instalment, I attempted to explain why the way we represent resume data, as well as the restrictions we enforce on said data, need to change to better leverage the fact that we, for years now, have machines that can help us perform the initial resume filtering and analysis. In the next instalment, we’ll cover the methods (and people) we currently use to evaluate resumes and why these must also be changed (drastically). I’ll share my experience when querying LLMs about my own resume (as I suspect many recruiters do) and demonstrate how misleading the results can be (hint: very!).

As noted in part I, I welcome comments and discourse and have started formulating a plan to address these issues. I firmly believe it’s more than feasible and, from a technical standpoint (the human aspects are a different story), not overly complex. If you care, please take part and voice your opinions.

So, how do we avoid this potentially most expensive mistake?

• Never commit secrets to any repo. You might think that if the repo is private, this isn’t a problem; if so, you’d be wrong:) Firstly, it may be private today but tomorrow? Who knows… (as an avid FOSS supporter, I certainly want all code to be open and there are plenty of examples of commercial entities that opted to do just that with their previously closed/proprietary repos).

Secondly, even if the repo will forever remain private, that’s not to say the source will not end up in the hands of less-than-benevolent people. So, what to do to protect our secrets?

• Consider using a secret management system (there are loads, FOSS and otherwise - run a search, you may already be using a platform that offers this particular service)
• However way you choose to store your secrets, make sure that any files containing them are included in the .gitignore file (if you use a different source control, find your counterpart, they all have them)

The above actions, good as they are, require all humans involved to adhere to these policies and, as you surely know, people often don’t. Luckily, you can make them:) Gitleaks is a project that aims to do just that. In its README, you’ll find a full GH Action example (similar hooks for other platforms are available, though writing your own is also easy enough) that runs this tool, as well as pre-commit one; and you do want both as it’s far better to catch these things before you commit. Make sure you include a note about how to set up the pre-commit hooks in your README because, once these things get into the commit log, purging them is, well, involved and annoying:)

Hopefully, you are now convinced that you should set these hooks up on any repo that includes (or may in the future include) sensitive data but what about all your existing repos and their commit histories? Well, as a first step, use gitleaks to detect compromised repos. Next, if you use Git (notice that Git is NOT shorthand for GitHub; in 2025, there’s a high chance you are using Git, no matter what platform you host your code on), take a look at git-filter-repo which is designed to assist with this purging task. You may also want to read Removing sensitive data from a repository. If you’re not using Git, check your source control documentation for its counterpart purging option.

Don’t be that person who could have prevented a crucial and embarrassing breach, but didn’t:)

Also, and it may sound odd to some but if you stop to think about it, I reckon you’ll agree that there are way too many combat scenes, each far longer than it needs to be. It takes away from the plot and alters your excitement threshold to a point where you’re thinking: “Yes, I got it. Neo is the one, he’s a demigod and he can fly like Superman (only his outfit makes him look cooler - again that word) and beat everyone’s arse. Can we get on with the story, please?”

Lastly, while watching the Trinity computer break-in scene in part II (Reloaded), I again marvelled at why Hollywood can’t get these scenes right. I mean, seriously, they pour millions of dollars into these productions, how much would it cost to hire a consultant like me to make it believable? I’d have done it for the relatively humble sum of $100 (plus credits).

Unlike most films, it seems that they DID consult someone because the use of actual utilities is depicted in the scene (nmap and ssh) and the “CRC32 exploit” reference alludes to a real CVE (see 2001-0144) and clearly, someone also told them it’s more realistic for the fictional sshnuke util to reset root’s passwd rather than output the existing one (because passwds are hashed).

To me, it makes the scene more disappointing in a way. Why? Let’s analyse.

Here’s how the scene goes down:

Trinity sits down and gets to typing. She inputs very few characters and then we’re shown:

• The truncated output of nmap in a readable resolution (but not the arguments used). Seconds later, we’re shown the full screen from a farther angle. I couldn’t read from it but I did find this article on nmap.org so I know the full command was nmap -v -sS -O 10.2.2.2
• full command (arguments included) for the fictional sshnuke util
• full ssh command to get to the mysterious 10.2.2.2
• at this point, she lands in the “RRF-CONTROL” shell (convenient!) and types: disable grid nodes 21 - 48

Let’s break this down:

• She already has access to a super user shell (presumably, based on the fact PS1 starts with “#” and the use of -sS). But you know what? I’ll buy that because the scene opens with two security guards looking at a passed-out person over their desk, wondering “what the hell happened here?!”. So, okay, that person had the terminal open and something happened and Trinity walked into that situation, fine.
• 10.2.2.2 is a class A (CIDR) addr. Okay but how did she know that’s the machine to SSH to in order to get to the “RRF-CONTROL” interface? I mean, you want to depict the use of nmap? how about using -sn for host discovery and working things out from there?
• She invokes the nmap with -v -sS -O. Let’s break these down as well:
• -v stands for verbose (unimportant)
• -sS is SYN stealth scan (half-open scan) - a technique that sends SYN packets without completing the full TCP handshake. That’s the default Nmap scan type when running with super user privileges so she could have saved some typing but still, okay:)
• But now, we get to -O: Enable OS detection. This one is super important because it makes the scanning significantly slower. On my own laptop nmap -v -sS -O localhost takes roughly 12 seconds, whereas without -O, it takes a little over 0.900 seconds (try it, you’ll see).

And that brings us to the real question: why does she even need nmap here? CVE 2001-0144 affected many different OSes and SSH servers, not a particular one. Even if she wants to know the version of the SSH server, telnet 10.2.2.2 22 is much faster. TCP 22 is the default port, which frankly, is the only insight nmap gives her (notice the “No exact OS match” in the output). nmap in this situation, would make sense if trying TCP 22 FAILED and she needed to discover what alt port the service listens on. Moving on…

• This sshnuke util, bloody F is it doing on that machine? At least show her mount a USB stick to run this thing?!
• This “RRF-CONTROL” shell:
• How does she know its sub-commands?
• 3 separate args to denote the node range (21,-,48), seriously?!

Hollywood producers: if you happen to encounter this post, I’m “open for work”. I can help you make these scenes realistic while still keeping them tight (timeline-wise) and fast-paced:)

This has been the case for many years, possibly decades; however, recent circumstances made it far more pressing. Many people, myself included, have been ranting about it but I’ve yet to see a concrete plan to address the current state of affairs.

In this proposed series of articles (perhaps the word manifest is warranted), I will attempt to break the problem into its sub-components and propose detailed, possible solutions. I will focus on my industry (to wit: software development - stick with what you know is always a good rule); however, many of my salient points also apply to other domains and I will leave this extrapolation as an exercise to the reader (for now, at any rate).

At times, for the sake of brevity, rather than detail everything that is being done wrong, I will simply outline how it should be done, instead. Comments are most welcome.

Candidate Filtering

The first step when compiling a pool of quality candidates is to provide a concise, accurate job description. This is the cornerstone of the entire process and failing to do so will severely hinder the overall process and have a heavy effect on the overall result. If you can’t communicate what you’re looking for, your chances of finding it dramatically decrease.

Job Descriptions

Job descriptions must be written by those who, at least at some point in their career, have done the job or, failing a perfect match (perfection is to be chased, hardly ever to be achieved), a comparable job, with contributions from those who are now managing people who perform this exact role or one most similar to it. As with many things (though not all), the quality of the description is likely to improve by requesting inputs from multiple individuals in different roles.

For example, when looking for a PHP developer to join a team of five, the description should be compiled based on inputs from:

• The direct manager of said team
• Two leading team members (establishing who these two are is a challenge in its own right; one that accounts for many of the problems covered in this essay but we’ll get to that)
• One or two representatives from units the team in question works most closely with (QA, Project Management, Account Management, Support, etc)

Why is this so important? At the risk of stating the obvious, the objective of this elaborate process is to locate candidates with the highest chance of succeeding on the job. For this, one must first describe the day-to-day nature of the role:

• Compensation range (a meaningful one - not 50k-120k) and location (on-site, hybrid [and if so where] or remote).

• The technical work; which, in the case of software development, is done chiefly by conversing with machines (if that’s not the case for your company, you’re doing it wrong!). This type of communication, however, has many subtleties. While all programming languages (and this applies to frameworks and operating systems as well) share many common similarities, and a good programmer can certainly adapt and learn on the go (in fact, if one can’t, one should seriously consider a change in direction), there are also many differences and, if one truly loves this particular vocation, one will develop specific opinions, tastes and preferences and these will have a significant effect on one’s productivity and satisfaction. As I write this, I am so tempted to illustrate this point with detailed examples; I will delay my gratification for the time being and instead, state the bottom line: the job description must include a high-level description of the technical stack one will be working with. The stack will change over time (revisit the point about adaptability) but, in most cases, not drastically.

• The human interfaces; with the former point in mind, ultimately, we do not write software to entertain machines (that’s the lovely thing about machines - they haven’t such needs); we write software for (and often with) humans, with the aid of machines. A programmer is, in essence, an interface between the machine and various human players (end-users and company stakeholders). A role can be most interesting and satisfying from a technical standpoint and still be a nightmare if the human elements are misaligned. The job description should strive to depict this collaboration as accurately as possible; to wit: what sort of people will one collaborate with as part of the role, using what means/protocols/systems?

This last statement (put in the form of a question) requires clarification, lest it be misunderstood. By “what sort of people”, I do not mean a meaningless list of superlatives (best, talented, kindest, brightest, supporting, open-minded, you get the idea). There’s an astounding amount of that tripe in many job descriptions (and resumes). Not only is this meaningless (self-praise without supporting evidence always is), it is, in fact, counterproductive, as it makes the description far longer and is typically placed in the beginning, which means that, by the time you get to the important bits (if you haven’t given up altogether), you suffer from fatigue.

• A succinct blurb about the company. With succinct being the operative word (again, not an abundance of self-praise and lengthy paragraphs about its love for diversity and support of world peace). Just facts: the vertical/industry, clientele, headcount, location, product line. And, on the subject of diversity and world peace, here’s a universal truth: people who emphasise their support of these things have a problem they are trying to compensate for. Those who truly support equality (which leads to diversity) do not feel the need to explicitly state it. It’s like recounting sexual endeavours often and in great detail without the slightest prompting. It’s a tell.

To recap, a job description must:

• Be written by the people who do the actual work (to put bluntly - not professional recruiters and certainly NOT HR)
• Be limited to: compensation and location, technical outline and the human characteristics and propensities (not superlatives and meaningless accolades!) of those involved as well as those expected from the successful candidate

Important note: the order in which these elements are written also matters. I chose to list compensation and location first, not because I believe it’s necessarily the most crucial consideration but because it’s the shortest, while still being a major factor. To illustrate the importance of accuracy here, lying about this aspect is akin to using a picture of Brad Pitt in your dating profile (assuming you do not look like that, of course, hence the “lying” bit), you’re just wasting everyone’s time and, as with dating, the candidate will not fall in love with you and forget all about this deception because of your winning personality.

As the overall problem is complex, I think it best to outline it in easily digestible instalments and this seems like a good stopping point.

In the next instalment, I will discuss the current approach towards resumes and why it so painfully fails to serve the end goal. Some salient points for reflection:

• While the means of initial filtering drastically changed (from a manual review by a competent human to automatic parsing by software), the format has not changed at all and, worst still, there’s no universally adhered standard to use for the parsing/data extraction process
• With the advent of a multitude of programming languages, each with loads of popular frameworks and constructs, technology has become both far more complex and complicated and the filtering algorithms are not advancing accordingly
• Emphasis on the wrong, least significant aspects during the initial candidate evaluation (hint: self-praise yet again, with too little supporting evidence)

As noted in my opening statement, I welcome comments and discourse and have started formulating a plan to address this issue. I firmly believe it’s more than feasible and, from a technical standpoint (the human aspects are a different story), not overly complex. If you care, please take part and voice your opinions.

I’m pleased to announce the release of super-zaje which can do everything zaje can but introduces one very useful enhancement: thanks to the magic of tesseract and gosserac, super-zaje is able to extract text right off an image (both HTTP(s) URLs and local files are supported).

The below video demonstrates its usefulness with a few sample LinkedIn posts that shared code as screenshots (a common case, alas, due to LI’s inexplicable refusal to support markdown)

For installation instructions, see README

Thanks to ASCIInema, you can copy everything displayed in the shell right off the player. Simply pause, mark and copy as you normally would. If you prefer, you can also download the file and play it locally in your own shell with asciinema.

Enjoy:)

This caused a mini storm; with this article, I aim to:

• Succinctly explain this move and its implications (hint — not as dramatic as some people make them seem)
• Offer my opinion as to why RH decided on this approach

The actual move

Below is a quote from RH’s official press release:

We are continuing our investment in and increasing our commitment to CentOS Stream. CentOS Stream will now be the sole repository for public RHEL-related source code releases. For Red Hat customers and partners, source code will remain available via the Red Hat Customer Portal.

Okay, two questions may come to the minds of those reading this:

• What exactly is this CentOS Stream?
• What’s the source code in question?

Let’s start with the first question; from https://www.centos.org/centos-stream:

Continuously delivered distro that tracks just ahead of Red Hat Enterprise Linux (RHEL) development, positioned as a midstream between Fedora Linux and RHEL.

This may confuse some people because CentOS was, to use a kind term, repurposed a while back and those who have not followed that change will find this definition doesn’t match their understanding of what it is. Basically, to rephrase the above: CentOS Stream is RHEL’s upstream.

Right. Now what sources are we talking about? After all, RHEL is a Linux distribution (and one of many, at that); it does not own the kernel (which is provided under the terms of the GNU General Public License version 2) so, when the word “source” is used in this context, what does it refer to?

I imagine anyone who is interested in this topic has at least some vague idea as to what a Linux distribution means but I’ll provide my own little blurb here. Before I do that, however, I should note that there are different kinds of distributions; Redhat is a binary software distribution, whereas Gentoo (to name the leader of its kind) is based on the idea that you compile sources on your own machine using its Portage package management system.

A “binary” Linux distribution takes the kernel sources, as well as those of many many other projects/components (GCC, BASH, libpng, Golang, Rust, PHP, X-server. GNOME, KDE, Xbill, etc) and packages them in a way that’s easy to deploy and upgrade.

In the case of RH, the packaging format is RPM (Redhat Package Manager). RPM, while a Redhat invention, is also FOSS and is used and contributed to by many other Linux distributions, as well as independent developers. Another example for a commonly used FOSS project conceived at Redhat is logrotate (there are many others).

Okay, so Redhat (as well as many other distros) builds and packages a multitude of FOSS components (some of which it also developed and maintains) so that we won’t have to do it ourselves. As you can imagine, this takes a lot of work (there are many packages!) and, as they’re doing it, they encounter bugs, to which they apply patches (before compiling). They then contribute these patches upstream (when appropriate — sometimes, the patch is only needed in order to package the source for a Redhat distribution).

So, “source” in this context mainly pertains to the RPM specs used to generate the packages and the patches applied during the build process. RPM Source packages are also referred to as SRPMs.

Now that we understand what CentOS Stream and “sources” mean in this context, who will be affected by this decision?

As emphasised previously, there are many binary Linux distributions. One, very broad, way of segmenting these would be based on the packaging format (and accompanying tool-chains) they use; with the two most common ones being: deb and RPM.

Side note: deb is my format of choice, conceived by Debian, my favourite distro. One example of another distro that uses this format is Ubuntu. I could (and perhaps should) write a whole article about the relationship between Debian and Ubuntu and another that compares between these two packaging formats but neither pertain to this RHEL decision so, I’ll leave it at that for now. I have started writing a series of articles about software packaging; if you’re interested in this topic, you can find the first instalment here.

As noted above, RPM is Redhat’s packaging format of choice and there are many different distros that use it as well. Some of these distros consider being binary compatible with RHEL releases their main selling point. I use the term “selling” quite loosely here, as in many cases, no money is exchanging hands.

To better understand this rather intricate ecosystem, let’s consider how Redhat generates (large portions of) its revenue. There are two main streams:

• Professional Services
• Technical Support

To demonstrate the value of these two propositions, let’s consider a person I know intimately: myself(!).

As you already know if you got this far, I am a Debian user. I’ve used it exclusively on all my personal machines and when the choice was mine to make, on all servers under my control as well.

Again, I could write volumes about why I love Debian as much as I do but I (and Debian) am not the topic of this particular article so I’ll be brief and say that the main factors are:

• It’s a community distro that matches my ideology
• Its release cycle and repo segmentation make sense to me
• I find deb (and the accompanying tool-chain) superior to that of RPM (and its tool-chain)
• The package quality is extraordinary; regardless of whether you compare it with commercial distros or fellow community ones

Having said that, would I choose Debian if I were the CTO of a vast financial consortium with thousands of technical staff? No, I’d actually choose Redhat.

Why? Because while I, as a one man band, can easily maintain a 100 Debian servers of different configurations and purposes (and even more than that by putting in place automated procedures), this imaginary CTO version of me (to be clear: I’ve no aspiration to become that person) cannot. He also cannot personally interview his 1000+ employees to ensure that only like minded people that can are on the payroll. You see, Debian has many hard working, bright volunteers and they produce excellent packages and, if you know how to investigate, solve and report issues, you will also get superb support from the community but, if you don’t, you’re better off paying for a Redhat subscription. In return for your subscription fees, Redhat’s support will squeeze the information out of you/your employees like one squeezes tooth paste out of the tube. They will not send you off with a friendly RTFM (see this article for my views on how important the RTFM notion is) and you could also report back to the board and say: “It’s being looked at by RH” and be sure that no one will fault you for anything. Google “No one ever got fired for purchasing IBM” for more on the latter point.

Right, so, that’s why, in my opinion, people opt for RHEL.

Now, who is affected by this decision? The RHEL clones.

At this point, you may be thinking: “Okay, Jesse, got it but, if the only reason to pay for RHEL is so you could benefit from professional services and tech support (and arse coverage), why would you opt for one of its binary compatible clones instead?”

Once more, in my view, two use cases:

• As a contractor working with a company that uses RHEL, I want to work on the closest thing to it without paying for a subscription
• As the aforementioned CTO, I want my tech chaps to have the closest thing to it on their dev machines without paying for a subscription (on Prod, I’ll pay, to get the benefits we already covered)

It is well worth noting that this move by Redhat is unlikely to eradicate these so-called clones, it will merely make life a bit more difficult for them.

From https://www.phoronix.com/news/Rocky-Linux-RHEL-Source-Access:

“These methods are possible because of the power of GPL. No one can prevent redistribution of GPL software. To reiterate, both of these methods enable us to legitimately obtain RHEL binaries and SRPMs without compromising our commitment to open source software or agreeing to TOS or EULA limitations that impede our rights. Our legal advisors have reassured us that we have the right to obtain the source to any binaries we receive, ensuring that we can continue advancing Rocky Linux in line with our original intentions.”

Now we arrive at the other question…

Why did the Redhat take this step?

Redhat does not care about the community clones. It knows that people using these will not buy a Redhat subscription if they were to disappear. They’ll go with Debian (or Ubuntu or one of the numerous RPM based distros available).

Who do they care about? Oracle Enterprise Linux .

From https://en.wikipedia.org/wiki/Oracle_Linux:

Oracle Linux (abbreviated OL, formerly known as Oracle Enterprise Linux or OEL) is a Linux distribution packaged and freely distributed by Oracle, available partially under the GNU General Public License since late 2006.[4] It is compiled from Red Hat Enterprise Linux (RHEL) source code, replacing Red Hat branding with Oracle’s.

Do I support Redhat’s decision? No , I don’t. When you base your business model on FOSS (see https://medium.com/@jesse_62134/dont-forget-to-floss-25f3faa3856 for why I think it’s the best choice), you enjoy many benefits (too many to list in this article) but, you also need to prepare yourself for things like Oracle Enterprise Linux.

Can I understand how Redhat would be irked by Oracle Enterprise Linux? Absolutely but again, it’s part of the deal.

Psst..

Liked this post and have a role I could be a good fit for? I’m open to suggestions. See https://packman.io/#contact for ways to contact me.

Cheers,

In the last segment of this series, we briefly discussed the importance of starting the build process from a clean ENV. We left off promising to say a word about pkg-config and move on to how proper packaging helps matters, how utilising chroots made things far easier way back when, why Docker was the next evolutionary step and, lastly - why, while grand, it is not an all encompassing, magic-holly-grail solution to all your build and deployment headaches. So, without further ado…

pkg-config

As I often recommend doing, let’s start from looking at the man page:

pkg-config(1) General Commands Manual pkg-config(1)
NAME
pkg-config - Return metainformation about installed libraries
DESCRIPTION
The pkg-config program is used to retrieve information about installed libraries
It is typically used to compile and link against one or more libraries.
Here is a typical usage scenario in a Makefile:
cc program.c `pkg-config --cflags --libs gnomeui`

Okay, that’s a clear and accurate description. The key bit here is this:

It is typically used to compile and link against one or more libraries.

So, pkg-config can help us ascertain that we have the needed deps to build our software.
Let’s look at a package (I chose libgif7, completely at random - I literally typed dpkg -L libg, hit tab-y and chose one) on my Debian machine to understand what pkg-config actually does for us.
Here we can begin to see the advantage of packaging formats like deb and RPM, to wit: they store the installed packages in a local DB and provide tools to look up metadata about them. In the case of APT/deb/dpkg, if we want to see what files a given package includes, we can run:

dpkg -L

Sample output:

$ dpkg -L libgif7
/.
/usr
/usr/lib
/usr/lib/x86_64-linux-gnu
/usr/lib/x86_64-linux-gnu/libgif.so.7.2.0
/usr/share
/usr/share/doc
/usr/share/doc/libgif7
/usr/share/doc/libgif7/NEWS.gz
/usr/share/doc/libgif7/TODO
/usr/share/doc/libgif7/changelog.Debian.gz
/usr/share/doc/libgif7/changelog.gz
/usr/share/doc/libgif7/copyright
/usr/lib/x86_64-linux-gnu/libgif.so.7

Very helpful, indeed:)

NOTE: in this post, I’ll be mentioning several deb/dpkg/APT commands (I’m a proud Debian GNU/Linux user). Of course, not all Linux distros and certainly not all UNIX flavours use this toolchain/stack/your term here. Since RPM/YUM/DNF is a very common stack, I’ll make a reasonable effort to provide the counterpart commands for these as well. In this case, the counterpart of dpkg -L is rpm -ql.

You’ll notice that the above output includes no reference to any pkg-config files at all. To understand why, allow me to provide some background as to how Linux distros based on pre-built/compiled packages segment things and why.

Let’s start with the why : it is commonly agreed (though not always practised) that a file system should not have files (of any kind: config, binaries, scripts, what have you), the system does not need in order to function. In the early, more naive days, this was mainly a question of disk space, which was very limited. With today’s resources, this point is somewhat less important (though not always — consider embedded devices) but, with the advancement and general availability of tech and computer resources, another problem has emerged; to wit: SECURITY. Put simply:

The more unneeded rubbish you have on your FS, the more vulnerable you are.

Another difficulty that has become more pronounced is that of managing dependencies and of course, the fewer packages you have installed, the easier it is to manage them.

Now, let’s go into the how. Again, I’ll be covering how it’s done in deb based distros, as well as RPM based ones. The principle in both is the same:

Packages are built from a spec file (or, in the case of deb — multiple spec files, each serving a different purpose).
The spec defines the package deps (separated into those needed to build the package and those needed to run it), as well as specifies the files to be included in the package (binaries, configuration files, documentation, etc) and their location (this is fixed, you cannot choose where to install files when deploying deb and RPM packages). It also includes some metadata: package name, description, source and so on. Some of the metadata is mandatory to specify (name for instance), other bits are optional (for example, not all packages declare the source/repo the package came from, which is a shame, because it’s useful data).

Now, to bring us back to the question of why the libgif7 package includes no pkg-config files: one spec can declare multiple packages and, in the case of libraries like libgif typically will.

To better explain this, let’s obtain the spec files for this package from my Debian 11 repo. We can do that with:

$ apt-get source libgif7

If you’ve run the above command, you’ll find that it has placed a directory called giflib-$VERSION in your CWD.

Inside it, you’ll find many different files, including the source for libgif of the version in question and a directory called debian where the spec files reside. Here’s what’s in there in my case:

-rw-r--r-- 1 jesse jesse 14506 Dec 20 2020 changelog
-rw-r--r-- 1 jesse jesse 1328 Dec 20 2020 control
-rw-r--r-- 1 jesse jesse 2371 Dec 20 2020 copyright
-rw-r--r-- 1 jesse jesse 10 Dec 20 2020 giflib-dbg.docs
-rw-r--r-- 1 jesse jesse 303 Dec 20 2020 giflib-tools.doc-base
-rw-r--r-- 1 jesse jesse 10 Dec 20 2020 giflib-tools.docs
-rw-r--r-- 1 jesse jesse 9 Dec 20 2020 giflib-tools.install
-rw-r--r-- 1 jesse jesse 24 Dec 20 2020 giflib-tools.manpages
-rw-r--r-- 1 jesse jesse 10 Dec 20 2020 libgif7.docs
-rw-r--r-- 1 jesse jesse 18 Dec 20 2020 libgif7.install
-rw-r--r-- 1 jesse jesse 1701 Dec 20 2020 libgif7.symbols
-rw-r--r-- 1 jesse jesse 10 Dec 20 2020 libgif-dev.docs
-rw-r--r-- 1 jesse jesse 46 Dec 20 2020 libgif-dev.install
drwxr-xr-x 2 jesse jesse 4096 Dec 20 2020 patches
-rwxr-xr-x 1 jesse jesse 887 Dec 20 2020 rules
drwxr-xr-x 2 jesse jesse 4096 Dec 20 2020 source
drwxr-xr-x 2 jesse jesse 4096 Dec 20 2020 upstream
-rw-r--r-- 1 jesse jesse 211 Dec 20 2020 watch

Let’s focus our attention on some of these:

• control: defines the metadata for the packages to be produced (name, description, section and, very importantly: the build and runtime dependencies)
• rules: contains the build instructions (this will typically be processed by make but it’s not a requirement — you can use any tool you want, just remember to declare it as a build dep)
• patches: in some cases, the package maintainer will apply patches to the upstream source (what is often referred to as pristine sources in RPM terminology). These will be placed in this directory and processed when rules is executed
• changelog: this is a very important file; amongst other things, it allows us to easily tell what an upgrade includes (security fixes, new features, bug fixes and also breaking changes)

Right, this is all very interesting but again: why doesn’t the libgif7 package include any pkg-config files? Because they are part of the libgif-dev.

NOTE: in RPM/YUM/DNF based systems, the package spec consists of a single file (package-name.spec) rather than multiple files as described above. The general concepts are very similar, however, and the spec file is divided into sections, each serving as a counterpart to the above debian spec files. Patches will typically reside under ~/rpmbuild/SOURCES. The naming convention for development packages is package-name-devel.

As we said before, one spec can declare several different packages and this is the case for many packages, especially those providing libraries. Let us take a closer look at the control file; for the benefit of shortening this article, we’ll use grep to extract the different packages this file declares:

$ grep "Package:\|Description" debian/control
Package: giflib-tools
Description: library for GIF images (utilities)
Package: libgif7
Description: library for GIF images (library)
Package: libgif-dev
Description: library for GIF images (development)

Okay, so, we can see that 3 packages are declared in this spec. We’ve already seen what files libgif7 contains, let’s now look at libgif-dev:

$ dpkg -L libgif-dev
/.
/usr
/usr/include
/usr/include/gif_lib.h
/usr/lib
/usr/lib/x86_64-linux-gnu
/usr/lib/x86_64-linux-gnu/libgif.a
/usr/lib/x86_64-linux-gnu/pkgconfig
/usr/lib/x86_64-linux-gnu/pkgconfig/libgif7.pc
/usr/share
/usr/share/doc
/usr/share/doc/libgif-dev
/usr/share/doc/libgif-dev/NEWS.gz
/usr/share/doc/libgif-dev/TODO
/usr/share/doc/libgif-dev/changelog.Debian.gz
/usr/share/doc/libgif-dev/changelog.gz
/usr/share/doc/libgif-dev/copyright
/usr/lib/x86_64-linux-gnu/libgif.so
/usr/lib/x86_64-linux-gnu/pkgconfig/libgif.pc

As you can see, the dev package includes a directory called pkgconfig which has a single file called libgif7.pc and another file called libgif.pc which is a symlink pointing to the former.

To reiterate: the purpose of this package segmentation convention is to avoid the unnecessary deployment of files on our filesystem. dev packages include files that are only needed for developing with (or building against) a given package (headers, archive files, pkg-config files, etc).

Let’s have a look at the contents of pkgconfig/libgif7.pc:

prefix=/usr
exec_prefix=${prefix}
libdir=${prefix}/lib/x86_64-linux-gnu
includedir=${prefix}/include

Name: libgif
Description: Loads and saves GIF files
Version: 5.2.1
Cflags: -I${includedir}
Libs: -L${libdir} -lgif

As you can see, it provides information we’ll need when building against this library:

• Its prefix
• Where the library files (shared objects, archive files) reside
• Its version (remember our description of the dependency hell?)
• Cflags in this case only setting the include path (-I) but potentially, it could specify other flags to be used by the compiler
• Libs points the linker to our $libdir (-L) and specifies that we should link against libgif (-lgif)

Let us look at a more elaborate example: the pkg-config for gtk4:

$ cat /usr/lib/x86_64-linux-gnu/pkgconfig/gtk4.pc
prefix=/usr
includedir=${prefix}/include
libdir=${prefix}/lib/x86_64-linux-gnu

targets=broadway wayland x11
gtk_binary_version=4.0.0
gtk_host=x86_64-linux

Name: GTK
Description: GTK Graphical UI Library
Version: 4.8.2
Requires: pango >= 1.50.0, pangocairo >= 1.50.0, gdk-pixbuf-2.0 >= 2.30.0, cairo >= 1.14.0, cairo-gobject >= 1.14.0, graphene-gobject-1.0 >= 1.9.1, gio-2.0 >= 2.66.0
Libs: -L${libdir} -lgtk-4
Cflags: -I${includedir}/gtk-4.0

This one includes another field called Requires which specifies additional deps (similar to what the debian/control file does).

So how is this metadata used? Generally speaking, the steps when building C/C++ code are:

• Generate and run the configure script to specify the features you want to build the project with (i.e: libgif support) and ensure all project deps can be found
• Build the code using a compiler (can be done by invoking make with a Makefile, which will in turn, invoke other tools including the compiler, but many other build frameworks/tools may be used, for example: CMake.
• Link against needed deps using ld
• Optionally, install the resulting files (binaries, configs, metadata, man pages, etc) onto the target paths

pkg-config will typically be involved in the configuration stage. For example, a configure script for a project that requires GTK4 may include this command:

$ pkg-config --cflags --libs gtk4

Which will return an output similar to this:

-mfpmath=sse -msse -msse2 -pthread -I/usr/local/include/freetype2 -I/usr/include/gtk-4.0 -I/usr/include/pango-1.0 -I/usr/include/harfbuzz -I/usr/include/pango-1.0 -I/usr/include/fribidi -I/usr/include/gdk-pixbuf-2.0 -I/usr/include/x86_64-linux-gnu -I/usr/include/cairo -I/usr/include/pixman-1 -I/usr/include/uuid -I/usr/include/harfbuzz -I/usr/include/libpng16 -I/usr/include/graphene-1.0 -I/usr/lib/x86_64-linux-gnu/graphene-1.0/include -I/usr/include/libmount -I/usr/include/blkid -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -lgtk-4 -lpangocairo-1.0 -lpango-1.0 -lharfbuzz -lgdk_pixbuf-2.0 -lcairo-gobject -lcairo -lgraphene-1.0 -lgio-2.0 -lgobject-2.0 -lglib-2.0

At this point, you may be wondering why we need pkg-config at all if, as we’ve seen, deb/RPM based distros have tools that can provide the same information. The answer is rather simple but instead of phrasing my own version of it, let’s have a look at what Wikipedia has to say; from https://en.wikipedia.org/wiki/Pkg-config:

pkg-config is defines and supports a unified interface for querying installed libraries for the purpose of compiling software that depends on them. It allows programmers and installation scripts to work without explicit knowledge of detailed library path information. pkg-config was originally designed for Linux, but it is now also available for BSD, Microsoft Windows, macOS, and Solaris.

The imperative words here are: unified interface.

There are many Linux packaging formats but, while you can install the deb toolchain on an RPM based distro and vice versa, as well as on some other Unices, doing so can cause confusion (was this package installed via RPM, dpkg or something else? where does its metadata reside and what tool should I use to fetch it?) and when writing your packaging/deployment scripts, you cannot really rely on either of these toolchains being present.

You could, of course, cover both cases with conditional statements but that would make for a very long, error prone and hard to maintain code. Further, these tools will only work with packages deployed through them. In other words, dpkg will not return data for files/packages that were installed by manually invoking make install or cmake –install or rpm -i.
Moreover, while distros like Debian and RedHat (to name only two) do go to great lengths to package a multitude of popular (and some less popular) packages, no single distro can cover everything under the sun and chances are you’ll still have to build SOME of your needed dependencies yourself rather than rely on pre-built packages from the official distro repos.

pkg-config is useful because it is a unified interface. Declare that your build depends on it and you’re covered:) As far as the building bit is concerned, it doesn’t cover SUCCESSFULLY INSTALLING pre-built binaries, which is why packaging formats like deb and RPM are so important.

At the point, it is worth mentioning that there are alternatives to pkg-config. One such prominent alternative is GNU Libtool.

Once more, rather than needlessly work on my own explanation, allow me to refer you to Wikipedia for a quick comparison: https://en.wikipedia.org/wiki/Pkg-config#Comparison_with_libtool

Right, let’s recap:

In this chapter, we’ve discussed the purpose of pkg-config and demonstrated some obvious advantages of the packaging approach deb and RPM share, as well as explained the reasoning behind package segmentation.

Join me for the next instalment of this series where I’ll return to the use of chroots, the added value provided by Docker and how we can combine proper packaging and Docker in our pursuit of the perfect build, packaging and deployment process:)

May the source be with you,

There are other things I could point out but while extremely annoying, they are either too much of an edge case to interest you or things I know you will not change because you think there’s a chance you’ll wear users down with. An example of the latter is your constant badgering about a free month of “Premium”. Just so you know, I will never pay for a premium subscription and I will also not opt in for a free month of it because you want my credit card in advance and, we all know how this works out… I should also note that when I did click on this call to action (just to see whether I’d have to provide a payment method in advance), I was confronted with a bloody questionnaire about my goals. Seriously? are you trying to get my money or give me a quarterly review?!

To those who don’t know the acronym, RTFM stands for Read The Fucking Manual. This used to have been a perfectly reasonable response to give when someone asked a stupid or super trivial question that is covered in the documentation.

I am not a huge fan of expletives and use them very rarely but since RTM is not as effective in driving the point home, I suppose, had I coined this acronym, I’d probably use “bloody” (Americans often think “bloody” is just the UK version of “fucking” but it isn’t so). But I digress…

At a certain point in time, it somehow became impolite to use RTFM and now, it appears to be perceived as plain rude. This is not because of the “fucking” bit at all. If anything, it seems that cursing is becoming more and more acceptable, not less.
So then, what is the reason for this change in norm and, why is it so important?

Well, let’s consider the notion this acronym conveys so succinctly; You’ve asked a stupid/trivial question. This implies that:

You have not read the manual which you are expected to do , and now, because you’re too lazy to read what I have read to be in a position to answer you (or even written myself for others to read, as the case may be), you’re needlessly wasting my valuable time

or:

You have read the manual and still managed not to know the answer to this basic question so… come on, don’t make me say it.

At this point, you may be thinking: “Jesse, that’s unfair! Maybe the questioner DID read the manual and it’s simply badly written?”

To this I say: indeed, manuals are written by people and people make mistakes. Thinking that’s something will be obvious to others because it is to YOU is a very common and human mistake to make. HOWEVER, when that’s the case, I’d expect the question to be prefixed with:

“I read the manual and in particular THIS section and couldn’t find the answer. I then proceeded to Google my question and looked at multiple results but still couldn’t nail it down. Could you please help me?”

If you prefixed your question in that manner and still got an RTFM reply then, you’re right, it’s unfair but, that’s hardly ever the case.

Another case I’m fine with and will never respond to with RTFM is when someone who is a friend or at least, a very close peer, prefixes the question with:

“I know it’s probably in the manual but, you’re quicker to ask and I’m very stressed at the moment…”

I’ll absolutely accept that. As humans, our behaviour is subjective and friends are more important than manuals.

These exceptions asides, basically, replying with RTFM berates the questioning party for failing to adhere to fundamental expectations: read manuals to learn what to do and, more implicitly — do not disturb others needlessly.

The reason RTFM is now considered rude is because we no longer expect that of people, which is extremely sad and yes, important. The rest of this post is an account of my opinion as to why and how we got to a point where we no longer have basic standards and expectations where it comes to learning.

It all starts with the bloody participant awards

I remember the first time I heard about participant awards. It was in an article written about a book discussing education and its results. Unfortunately, it was a rather long time ago (over 10 years) and I cannot find it, which is a shame. I have not actually read the book (or I’d certainly remember its title and author name), only the article about it. I tried Googling key phrases from it in an attempt to locate it but couldn’t. If anyone knows the book I’m describing, please comment.

At any rate, for those of you that don’t know, it has become common practice to give children an award, not for being the best at something but merely, for SHOWING UP. Yes, that’s right. A competitive event is held, one child performs better than all the others, others perform well, others still perform poorly and EVERYONE gets an award.

When I was growing up, we did not get awards for showing up and learning that this is now done drove me absolutely bonkers. At that time, what worried me (and the author of this book I cannot find) was that this sends the wrong message to children and will produce adults that cannot handle the real world. What I failed to predict was that, instead, the world will be changed by these very children.

Let’s take a step back here and talk about the generation of my parents (just to frame this — I am 41). My grandfather was my sole male role model growing up. I idolised him, I still do and he absolutely deserves it. As a child. he taught me how to do pretty much everything but computer programming, which I taught myself (I don’t believe he ever touched a computer, frankly but I think, had he been born a bit later, he’d have loved it). He was always kind, patient and accepting. I owe him everything. He never hit me or any of my siblings and I can only remember ONE occasion in which he yelled at us and even then, it was only because he was concerned that we’re disturbing my nan.

Why do I bring this up in this context? Because my mum once told me that, instructed by nan, he used to hit her and her siblings. My first reaction was complete shock and I was even inclined to believe that she’s lying (we’ve a very complicated relationship and I don’t trust her) but upon reflection, I suppose it’s probably true. I’m POSITIVE that he didn’t want to do that but yes, it was a different time and hitting children was considered an acceptable and even educational form of punishment. That proved to be bad practice so, we stopped doing it, which is a good thing!

Every generation thinks they are the best and that the preceding and subsequent ones are rubbish. I am aware of this and am not an exception to the rule. Further, the blessed influence of my granddad aside, I had a most rotten childhood so, I will not bring my memories of how my parents handled me as an example to support any of the observations I make in the following few paragraphs (I do lean into my personal experience towards the end of this post though — it’s unavoidable).

Having said that, one’s parents are not the sole influence on one’s young life and, reflecting on the general messages I have absorbed growing up, it was obvious that physical violence towards children (or anyone for that matter) is discouraged. It was equally clear that in order to get praise and do well, one has to work hard. I can’t recall an incident where the underlying message was that everyone is amazing and it’s enough to just SHOW UP.

I don’t mean to imply, by any means, that the educational methods applied to me and my peers were perfect. Far from it. And I have mates that suffered unjustly because of various syndromes I believe they now call learning disabilities (forgive me if it’s not the correct PC terms at the time of writing this, it’s hard to keep track).

So, that was my world growing up. Imperfect and often unfair towards those who are substantially different (substantially because everyone is different in one way or the other and feels it).

In some ways, one could say, perhaps rightly, that things are better now; at least in terms of accepting diversity of thought and abilities.
For example, I have Asperger’s. I went through my entire childhood and much of my adult life without being diagnosed. I was finally diagnosed at the age of 30, by a psychiatrist whom I came to consult about a, then new to me, syndrome called OCD. Would I have been better off growing up now? In that particular sense, perhaps. It’s possible that a young Jesse growing up today would have been diagnosed as autistic, rather than just labelled as weird and, it would have probably been a very good thing. At least in my case. I do know that this diagnosis, late as it was, has helped me: I can now refer people to a Wikipedia page and get a more favourable treatment when I behave “weirdly”.

But I think we’re now taking it to the other extreme. It seems to me that everyone (parents, teachers, the whole world and his sister) are afraid to give any criticism lest they hurt the child’s fragile soul. And this is what the participant award is all about. We’re so fearful that, if we were to say John or Jill did best at a competition, the other children will get upset and will be scarred for life so instead, we give EVERYONE an award. THIS IS WRONG.

It’s unfair to John and Jill because we’re not acknowledging their hard work and talent and it’s unfair to all the other children because we’re not encouraging them to find something they excel at. Everyone cannot be special at everything. If everyone is special then — NO ONE IS.

People of all ages want to be acknowledged for their special abilities and efforts and they want to be guided as to how to find and capitalise on these.

If you’re told that everyone is equally amazing and special, you’re essentially being told that there’s no reason to work hard. Which brings us back to the RTFM point. People don’t read the manual because, as children, they learned, from these very incidents and messages, that they don’t have to work hard to be successful or appreciated and that they, like everyone else, is amazing.

Let’s focus on this one word: amazing. It seems to be used so.. liberally these days. So much so that, one day, I’ve actually looked its definition up just to establish that I haven’t gotten it wrong all these years! Here it is:

Causing great surprise or wonder; astonishing.
Informal: very impressive; excellent.

Right. So, as I suspected, I did not get it wrong. When I use the word amazing, which I am incredibly discerning about, I mean exactly that: very impressive, excellent. I use it sparingly, because, let’s face it, most things are NOT very impressive or excellent. We have many other words to describe things that are not THAT; for example: ordinary, regular, normal, usual (and dozens if not hundreds of other words, in EVERY language).

To this day, and even after obtaining all the above insights, I am still extremely disappointed, borderline crestfallen even, when, after having “amazing” used in reference to something I have worked hard on and required skill, the same word is used to describe a most minimal effort.

Giving undeserved accolades and awards is hurting everyone, including the very people you’re trying to make feel good by doing so. Let me give you an example:

I like music. Not as much as I like programming but I like it. I started coding when I was 9. Not only did I receive no encouragement from my parents, I was actually discouraged by my mother (who thought and probably still does, that computers are an utter waste of time) and my efforts were further hindered by the fact that my sperm donor (I know him, I just don’t call him father) occupied our only computer through large portions of the day playing video games.

If you’re reading this and thinking that it’s very sad, I agree with you but here’s my actual point: when I was 10, I took some guitar lessons. This, I WAS encouraged to do because my mother liked music (presumably, I don’t recall her ever actually listening or commenting on music but I also don’t recall her saying it’s a waste of time) and my sperm donor was allegedly a rather gifted guitar player (I say allegedly because, as you’ll soon come to realise, I am in no position to judge such abilities). My mum paid for these lessons and I don’t recall having to beg or even vigorously ask for it (programming I learned by myself from reading programmes that came with QBASIC and, when I was 14, after having programmed a bit with QBASIC, I had to BEG her quite a bit until she agreed to pay for a book about C).

Anyway, I was no good. I don’t recall anyone actively telling me that I am rubbish at it (maybe they did and it just didn’t matter enough to register) but I definitely knew I am not very good and I felt no inner compulsion to work hard it either so, soon enough, I stopped the lessons.

While it would have been nice to be able to play well, imagine a world where, although I was no good, I’d have been told that I am amazing at it. Well, for one thing, whether you’re 10 years old or 41, we all like praise. I’d have probably kept playing (badly, while wasting my mum’s most limited funds) and maybe, I’d even develop a ridiculous dream (ridiculous in light of my lack of talent, I’m not saying NO ONE should cultivate that dream, there are, after all successful, excellent musicians that made an impact on many people, myself included) of becoming a rock star. Why is that bad? Because:

a. I am not talented at playing the guitar and could never, no matter how hard I worked, become amazing enough to succeed professionally

b. Because of my desire to excel, I’d be immensely frustrated by a.

c. I would have given less attention to something that I AM good at, love and make a decent living from, to wit: programming

Now, is it unfortunate that my mother did not encourage my natural tendencies? Very. Would I have become a happier adult if she had? ABSOLUTELY. But, would taking the opposite approach and encouraging me to stick with something I am clearly NOT good at resulted in a better outcome? ABSOLUTELY NOT.

And the same is true to how we engage with adults in all capacities. We should never tell someone they’re amazing at something when they’re not just to be “nice” or to avoid insulting them. Misleading someone isn’t nice. It’s counterproductive; to their well-being, yours, the organisation and society at large.

We SHOULD expect people to read manuals and learn on their own. We should not spoon-feed them and, if we’ve given them ample opportunity to perform and they haven’t, we should tell them so. I’m not saying we should be brutal and make them cry, of course. Giving constructive criticism is a very complex art, indeed, one that managers, teachers and parents should invest time in perfecting, but avoiding it because it doesn’t feel “nice” is not a solution.

Here’s to applying yourself,