There’s a whole group of Linux users out there (myself included), for whom we aren’t writing guides for. When you search for answers online, you find one of two types of write-ups: basic instructionals aimed at first timers, and advanced hacks for those who already have coding language or two under their belt.
But what about everyone in the middle? Those who know how to live in Linux, but aren’t developers? Can those who develop open-source software put themselves in the right mindset to write documentation for those who don’t know what they know? In most cases, the answer seems to be no.
Here’s an example: when I was interested in trying out Atom, I found this project, which include syntax highlighting for GitHub flavored Markdown. Great stuff, but how do I add it to the text editor? If I was only to use the maintainer’s readme file, I’d be lost on how to use it. Bad form.
On the other hand, here’s a project on GitHub from a former colleague with an excellent readme which covers not only installation. but common configurations and usage. Well done!
I’ve asked around, and I’m not the only one who feels that there’s a gap in tech write-ups. That’s why when we write guides for Linode </obvious product placement> we specify the prerequisite knowledge and link to those guides, and don’t cover anything that’s in them. But all new concepts are explained and exampled.
So if you’re a member of an open-source project, go take a look at your README. Would it make sense to someone who’s never used the language it’s written in? Do you explain how to install it, or expect the reader to already be familiar with make? Think about it please.
I came across this image on Facebook:
It inspired me to add my two cents.
I almost never repost this type of inspirational quote-in-picture media, but here’s something we need to repeat over and over.
The society and culture you live in has been carefully guided into place to push the glorification of celebrity and the perfect image. American mainstream culture is not deemed by the masses. Popular culture trends are dependent on the options set in front of the majority of people, and those options often come from the media and news sources, owned by the same people who profit from your weakness.
By creating a constant basis of comparison to an idealized image of perfection, unattainable by most, people will judge themselves harshly, and in secret. The self-doubt leads to fear, and fear is the main motivator for material consumption; either as a temporary solution, a distraction, or an escape.
The confident, self-assured human isn’t swayed by advertising for the latest health/cosmetic product. He has no need to drown his self loathing in addictive fast “food”. He doesn’t need to consume “reality” television.
Emotional stability is not profitable. Confidence is not profitable. But you are not a cash cow. You are an individual, and you are fine just the way you are.
EDIT: Changed some pronouns after a peer review. I don’t like using gender-specific pronouns when I’m talking about humanity in general, but until we decide on a gender-neutral singular pronoun there isn’t much I can do.
If you’re in tech, don’t let the constant stream of information on the latest and greatest distract you from how awesome it is to be living right now.
When I sleep, a 6” portable device with more computing power than it took to launch men to the moon sits next to me. It broadcasts wirelessly to my sound bar a computer-created piece of music with binaural beats and isochronic tones designed to help me sleep and dream.
The device also communicates wirelessly with an even smaller computer on my wrist, which tracks how much I move in my sleep. The device uses that data, along with the sounds of my snoring, to determine the best possible moment to wake me up, as I’m coming out of a REM sleep cycle.
As I go about my day my portable computer continuously streams music from the internet. As I go from home to car to office it wirelessly connects to various speakers. It reminds me when I have meetings, and alerts me as people talk to me over a half-dozen different mediums.
As I type my friend complains about the 20 seconds he has to wait for 10GB of data to transfer off his computer over USB 3.0.
I’m going through Seinfeld again on Hulu, and they have so many conundrums due to missing phone calls because they’re not home, losing people on the road and not having directions, not having the right trivial information at their disposal. If they had the same access to information that we’ve had in the last 10 years, the show would have lost half their story lines.
Here’s what I guess I’m getting at: Now is awesome. Don’t let yourself be jaded. Don’t think so far ahead that you don’t appreciate now.
I think it’s healthy once a day to go outside and look around. Look up. Take in how static and still the landscape is.
Then think about how you’re traveling in a circle at 1000 MPH around the center of the planet, while also moving at 67,000 MPH around the sun, all the while still moving at 45,000 MPH around the center of the galaxy. A galaxy which itself is moving at 1.34 million MPH towards the constellation Hydra
You’re never going nowhere, fast.
And if you’re a fan of Monty Python, you already know all this.
Yes, I am one of those people with a firm opinion on the Oxford comma. Most writers know the go-to example case for it, and if you haven’t, here’s a great visual representation.
In my particular field of technical writing you don’t see a need for it too often. If you’re writing out enough variables it’s often better suited to use a numbered or bulleted list.
But every so often I’m editing a piece and come across a sentence that can only be made better by adding that
extra last comma. It makes my… let’s be realistic and say hour.