Category / Advice

General advice. Clean up your room and get off my lawn!

by Douglas Black

What Are You Looking At? – An Essay on the Importance of Perspective

“No, Donny, these men are nihilists — there’s nothing to be afraid of.” (The Big Lebowsky, 1998)

Imagine you’re standing in the center of a large warehouse in pitch blackness. While it is so dark that you cannot see, you have an understanding that the room is not in any way ordinary — it has been imbued with a magic that allows representations of everything in existence to be stored within it in vast rows of organized shelves. It contains toys and weapons, delicacies and poison, fascinating mysteries and the drudgingly commonplace, loved friends and sworn enemies, Windows 7 and Windows ME, Ghostbusters (1984) and Ghostbusters (2016), and so on for a near eternity. However, you wouldn’t be able to see any of this in the darkened room at all, save for one trusty tool you find in your hand — a flashlight.

It’s quite a powerful flashlight, but the warehouse is so large that you can only see two or three sections of the warehouse at a time. When you examine the toy section, you find yourself feeling joyful as you pick up the playthings of your childhood and adolescence. As you shine your light on the section labeled “Conflict” and walk through its many shelves, you feel your gut fall into a dark void of hate, despair, and loss. Stumbling along, you find the “Love” section, and the dark void in your stomach is replaced by the warm glow of connection. You feel at peace.

In this allegory, the warehouse is your universe, and the flashlight your perspective from which to view it. The subject at hand is the way in which we view the world, and my purposes are to impress upon you its importance while also providing a method of crafting an optimal perspective.

Although it might seem long-winded to explain what may appear to be a simple word, I would like to first define the word “perspective” itself. It is critical to define its meaning for this essay, because our perspective is quite literally our reality: It is the seat from which we captain our ship. It is the sum total of the values, beliefs, and understanding a person holds in their mind at a given moment. It is also a closely linked to one’s own hierarchy of values, and thus any change to our values will shift our perspective (and vice versa).

While it happens that value hierarchies and the perspectives they generate are commonly found as part of classically identified ideologies (pre-packaged value/belief systems), they can also be encountered everywhere else from internet memes to literature. Unfortunately for us, because our perspectives are the product of a vast number of conscious and subconscious processes, it is very easy to let something influence us. To illustrate, let’s say we are having a bad day and we come across a faux-Folgers advertisement that says “The best part of waking up… Is when you don’t wake up”. Oof. Yeah, we chuckle, and we think we move on to the next thing — but by our implicit agreement with that sentiment, we allow a bit of that fatalistic negativity to subconsciously influence our perspective, tinging it just one shade darker. The reason so many of us struggle with unhealthy perspectives in the digital age may be the same reason many of us still eat fast food on occasion — when we’re in a rush and feel we need something now, our subconscious finds adopting a pre-packaged perspective irresistibly simple.

Some common pre-packaged perspectives today might include cynicism (disbelief in the altruism of others), pessimism (an imbalanced focus on negatives over positives), nihilism (rejection of higher meaning and shared values), or any one of dozens of black and white sociopolitical dichotomies. Don’t get me wrong; it’s entirely understandable that many people are cynical, pessimistic, or nihilistic these days, and there are undeniable benefits to these perspectives: a cynic is rarely disappointed in others. A pessimist is rarely surprised by bad news. A nihilist is freed from the burdens of moral consequence and responsibility. So what is the problem with adopting one of these broad, negative perspectives?

A perspective that’s simple and easy to understand has downsides. Just as a sizzling burger and piping-hot fries might satisfy at the time but leave us deeply regretful later, the long-term effects of a “fast-food” perspective, one that makes overly broad generalizations or logically inconsistent judgements about groups or entities, is far from optimal. For a nihilist, the benefit is also the drawback: if nothing matters, then everything is meaningless — so why continue living? For a pessimist, the continued focus on the negative side of everything is strongly linked to increased stress, anxiety, and negative health outcomes. For someone who uses a black/white dichotomy such as victim/oppressor, what may seem initially like a quick and easy way to know who and what is “good” and “bad” will quickly devolve into logical incoherence and schism once a complex issue is examined in detail.

Thus, the criteria for constructing a perspective shouldn’t just be whether or not it is accurate, but also whether it is beneficial. That is to say, a logically coherent perspective is objectively more useful than one that is logically incoherent because it will provide more accurate predictions, but a coherent perspective that also provides more benefits than another is clearly the optimal choice. It only makes sense that we should curate the perspective that will result in the best outcome for us — but what is “best”, anyway?

The concepts of “good”, “better”, or “best” imply comparison between two or more entities, where one thing is subordinate in desirability to another (see: value hierarchy). These judgements are based on the current situation one is experiencing. As Maslow’s hierarchy of needs demonstrates, when one is suffocating, air is better than water; when one is dying of thirst, water is better than food. So, what is best is determined by what we attribute the most value to in our circumstances — and that means this is something we must decide for ourselves based on our objectives and values.

We must try different perspectives to construct an optimal one. We must ask ourselves what we value and what our objectives are in our current state. Part of being human is trying out different things and seeing if we like it. In our early childhoods, we may value the love and validation of our parents, then the acceptance of our peers. As we get older, we may change to value the acceptance of a romantic interest, saving a targeted amount of money, or achieving certain professional goals. As we get older still, we may value more and more concepts such as love, understanding, or connection (perhaps these are all one and the same?). 

Ask yourself: What do I value most highly in life? What are my objectives? The perspective you choose should be the one that bears the most fruit. So now, allow me to return you to the darkened warehouse of my opening allegory, flashlight in hand.

Where do you choose to look?

Douglas Black is a Writer, Business Analyst, Lecturer, DJ/Producer, and amateur psychologist. He can be reached on his LinkedIn.

by Douglas Black

Common Documentation Problems & Solutions

We tend not to know the value of something until it’s gone, and that’s especially true for documentation. But how much does a lack of documentation really cost?

Let’s say that a given organization has eight new workers across all its departments. For the first three months of work, I estimate anywhere between 25-50% of those workers’ billable hours will be spent acclimating to existing systems and procedures and preparing their work environments for development. At an average rate of $45 per hour, that comes to a cost of $43,200 – $86,400 spent on acclimation in those first three months — and that’s that’s just for the new hires. Across all departments and systems, how many hours will the Operations & Maintenance teams spend working with systems each year? What about during a crisis? If there’s limited, inaccurate, or, even worse, no documentation, how many thousands of additional hours are being spent on getting up-to-speed across any given organization each year? In a small organization with 10 employees, roughly $45,000 will be lost each year due to a lack of documentation, and that scales upwards: without sufficient documentation, an organization with 100 employees will lose $450,000 per year; one with 1000 employees will lose $4,500,000 per year, and one with 3000 employees will lose $13,500,000 per year.

While cutting costs on documentation sounds at first like it’s trimming the fat, the reality is that a lack of documentation will slowly bleed an organization dry.

This article gives a brief overview of some of the most common problems an organization or individual might have with documentation and suggests an approach to fix it.

Problem: You don’t know who has the documentation for a system or application, or what you have is out-of-date.

Solution: Use a central repository for all documentation. Bonus points if it has some kind of version control: this could be SharePoint, OneDrive, Git, Confluence, or Wiki, but what really matters most is that it is SOP that all documentation from your department or organization goes to it. It should be organized intuitively and maintained regularly.

Problem: You aren’t sure where to get the right version of a required application or developer library.

Solution: Create a file repository on the same server as your central document repository. Organize all those different versions of Adobe, Apache, and Oracle apps (not to mention developer libraries!) in a way that’s logical for its purpose, which could mean bundling the files with the associated installation guides, or organize them by product. The most efficient method should be chosen according to the most common use-cases.

Problem: You find yourself having to open documents to figure out what they are.

Solution: Organize and name documents logically and consistently, and be sure to maintain this organization —it won’t help if you only use it for some documents but not others.Keep them hierarchical folder structure that is appropriate for your needs. Name your documents according to content, purpose, date, or any other criteria that you or others may be looking for. Just as an example, you might name your files according to the following format: <project name> – <document purpose> – <draft status>.docx. It may seem a bit basic, but you’d be surprised to see the jumbled file names on documents that get sent up to the very top (or from the top!) of a company or agency.

Problem: It takes too much time to find the information you need within your documentation

Solution: First, use MS Word’s Multilevel List feature to organize content in documents under clearly defined headings (plus, you can then quickly promote/demote the importance of a section using tab/shift + tab, which makes formatting much more time-efficient). Second, use Word’s auto-generated Table of Contents feature. This will generate a clickable ToC based on the headings in your document. You can make your documents even more convenient to navigate by using Word’s “Cross-Reference” feature, allowing a selection of text to be linked to another section anywhere in the document. Even better, all these interactable features will persist despite converting a DOCX to a PDF.

Another feature that helps save time is including a purpose section near the top of the document (usually near the introduction), so that readers can quickly determine if the document they are looking at is going to be useful to them.

Problem: You have documentation, but people have difficulty understanding and following it

Solution: There could be a few reasons for this, and I’ll go through the most likely culprits here. Firstly, the right medium needs to be chosen based on the message. Is the information a set of inputs/outputs and return codes for an API? It probably should be put in a table. Is it a list of database entities and their relationships? Make an Entity Relationship Diagram with a diagram or drawing app. Is it an introduction to the project including its history? It should probably be written in paragraph form and in chronological order.

And speaking of writing in paragraph form, this brings us to the next solution: make sure the information is organized in a logical and accessible way for your audience, i.e., the right level of background information and context is being provided. If it’s a Systems Design Document, it will be fairly technical, but if it’s an O&M guide, someone who was hired a week ago should be able to understand and follow it. But how can we write in a way that’s more logical and accessible? I’m glad you asked!

Generally speaking, information in writing should be presented from the most general first and get progressively more specific as it continues. One of the best tools to help writers understand this concept is what’s known as “the inverted pyramid model”

The inverted pyramid is a generalized model used for many different genres of writing, but the guiding principles of “general information -> specific information” and “more important -> less important” hold true regardless of whether one is writing an essay, news article, or technical documentation. If your article’s overall outline as well as the information in each paragraph follows this model, it will almost certainly be more digestible and easier to follow for readers of all levels of familiarity with the subject matter.

Conclusion:

If something is worth doing, it’s worth doing well, and that’s why just having documentation isn’t enough — it needs to be available, up-to-date, logical, organized, and understandable.

I hope these tips have been useful for you or your Technical Writer. If you have any questions or comments related to this article or writing documentation, feel free to reach out to me on LinkedIn.

by Douglas Black

If You Hate Writing, Learn to Write

If you’re reading this, chances are you think you hate writing.

You’re not alone: in more than a decade of teaching, I can’t recall students brimming with excitement on the first day of a writing class. It’s perhaps even worse in the business world, where it seems people would rather do just about anything other than be responsible for writing documentation, project charters, requirements, letters, or technical analyses.

But one must learn to write just as surely as one learns to breathe — our lives depend on it, because learning how to write is the very same as learning how to think.

Many people mistakenly feel the most difficult part of writing is putting pen to paper (or hands to keys) and spelling out the words, likely informed by unpleasant memories of cramped wrists and fingers from past exams written. But I swear to you that the most difficult thing about writing, by far, has nothing to do with the act of writing out language, but what comes before (and after): Thinking. I don’t mean it as an insult when I say most people don’t like writing because they don’t like thinking. It’s no wonder, however, because thinking is difficult.

Writing can be loosely categorized into four non-exclusive genres, including expository (establishing facts), persuasive (which I am trying to do in this essay), descriptive (crafting a mental image), and narrative (telling a story). I bring up these rhetorical modes because learning to write well in each one means honing our cognition in a crucial area. Remember that the way we do one thing is generally the way we do everything, and so by writing better, we’ll unavoidably be thinking better, too. Let’s break it down by genre and cognitive skill, starting with expository writing.

Learning to write expository texts means learning how to organize concepts logically so they can be learned by others. But is logical organization that important? Absolutely, because logical organization requires many cognitive sub-skills, as well. To logically organize and explain facts, this means you must be able to look at something, such as a car, software application, or manufacturing supply chain, and understand it (learning). Then, you must be able to organize all the entities comprising that thing into a hierarchy in a way that makes logical sense: i.e., pistons are a sub-component of an engine, and an engine is one of the primary mechanisms within a car. While wheels are important, too, they are not a sub-component of an engine, and should be organized differently, etc. Simply put, learning to write expository texts well means learning how to learn, learning how to analyze a system and organize it logically, and learning how to assess importance and create value hierarchies.

While persuasive writing depends quite heavily on expository writing as a pre-requisite in order for facts to be communicated, it also leans on thinking objectively and with empathy for others’ perspectives. Accordingly, it’s no surprise that the first rule of persuasive writing is to understand your audience. Thinking objectively (from different perspectives) is one of the most important sub-skills of critical thinking; it helps us separate ourselves from our egos and biases towards our preferred narratives, helping us take a step back from the zeitgeists of the age and do a self-diagnostic: does what I’m being told really match up with what I’m seeing? Who benefits? What incentives do I have to believe this is true? How does the scale balance once the evidence has been honestly stacked up? You might be surprised that what you’ve been taking for granted as the truth has been anything but.

Descriptive writing — the skill of being able to create mental imagery in our readers — isn’t just for aspiring novelists. Firstly, to describe something, one needs to notice it. Life is made up of the little details, and learning to appreciate them won’t just help you enjoy life, but it will help you develop an attention to detail that is necessary to be highly proficient in almost any pursuit. To be descriptive also requires that we choose our words carefully, with precision and a mind on how they will affect our audiences, helping us be more considerate and empathetic. Crucially, this means we will then also learn to think more carefully. Finally, being able to skillfully describe places, people, feelings, or other experiences is an excellent way to ensure you have the full attention of people when you communicate.

You don’t need to want to be the next Stephen King to learn to write narratives (stories), either. In his non-fiction book on the craft itself, aptly titled On Writing, King likened writing to digging around in dirt and excavating bones and artifacts that tell a story. I would like to modify his analogy somewhat. Narrative writing is not just the excavation of buried remains that tell a story, but a sort of archeology of the self: discovering what we have ourselves once buried and forgotten. When you sit down and write stories that draw from yourself, you are engaging in self-expression and discovery. You don’t need to publish it anywhere, even, but to put that which was hauled from one’s own hidden depths onto paper is to express what was crying out to be expressed. To understand yourself is to understand all of humanity.

If we don’t learn to properly think, we do so at our own peril. The world we live in is awash in examples of what happens when people only know how to follow rather than think. We will fail morally as we follow others into disaster without question, fail to communicate our wants and needs to those closest to us, fail to find our true selves through lack of expression and understanding, and ultimately fail to uphold our responsibility to ourselves in this world by falling far short of our potential. The mind is a weapon. Learn to wield it by learning to write, lest you be unwittingly wielded by others.

by Douglas Black

On Having Vision

Photo by Douglas Black

Author’s note: This essay was written in early 2019, when I was still living in my adopted home of Hong Kong.

“Wisdom is acting on knowledge.” God Help me, that’s a quote from Russel Brand, I think.

We live in an age of unprecedented access to information, and we’re only just beginning to understand the potential for it. Despite a few (hopefully soon to fade) black marks of internet censorship, we are all more informed than ever before on a global scale. We know about the current inferno consuming the Amazon rainforest, poverty (not financial, but lack of resources), climate change, tribalism, human-rights violations, etc. — but what can we actually do about it?

A lot, I propose.

What we’ve lacked historically is a lack of a vision for where we are going. Elected leaders are more focused on managing domestic issues, and few (if any, other than perhaps Barack Obama) were elected based on a positive global vision. But it looks like we need one now more than ever.

That’s what it looks like for me here in Hong Kong, but I’m sure that’s what it looks like for many elsewhere, as well. So again: what can we realistically do? Strive to make a difference with your personal conduct. I’m not going to quote Ghandi because I’m too affected to be trite, but it’s time we collectively look within, find our values, and adhere to them.

I’m not telling anyone to stop eating meat or to throw out your smartphone. I’m just saying that everything we do has an impact and we are all somehow connected by only a few degrees. I’ve been trying to stop eating fish and other seafood after I started seeing less and less fish in the ocean on my SCUBA dives; I’m now trying to not eat the meat of any animal I would not kill myself; I’m trying to help people be informed, find themselves, and connect with my writing and music. Maybe it helps (I think it does), or maybe it doesn’t. But it feels good to just try.

Nobody’s perfect, and I don’t advocate trying to be. But we need to stop trying to disconnect ourselves from our actions and instead try doing the opposite.

Find your ethics; listen to them; and then figure out what direction you want to head in. Hopefully, we’ll all meet somewhere in the middle.