Because of how many great open-source projects have empty readme files.
Because I like open-source software, but I’m not a developer. Even when projects are documented, it’s written for other developers. The assumed level of knowledge is that of the person who wrote it. I think like a user, not a dev.
Because when beginners enter issues on GitHub, they’re met with scorn instead of compassion. And when answers are given, the goal seems to be to give as little information as possible, and make the user chase down the real answer from clues and hints.
Because I hate being told “RTFM“. If I’m asking, I’ve already read the man page. The problem is, a man page generally only lists the options, and briefly explains what they are. Not how to use them, or why you would want to.
I’m a technical writer because I want to use great software without having to know how it was built in order to use it. Because the high learning curve associated with Linux comes in part because its users hoard their knowledge, and belittle those asking for a helping hand.
I’m a technical writer because I want everyone to be able to use the software they want.
Are you a technical writer? If so, why do you do it?
Last night I went to Zappa Plays Zappa, the show where Dweezil Zappa and a group of very talented musicians performs Frank Zappa songs. It was an amazing show. Jen and I were especially impressed with Scheila Gonzalez, who played several instruments perfectly, including a downright amazing saxophone solo, and sang with amazing range.
Since it’s the 40th anniversary of the album One Size Fits All, they played most of the album before doing other hits. If you’re not familiar with Zappa or the album click here and listen to about a minute of it. We sat in the third row left of center, right in front of the trumpet / trombone / guitar player, so it was pretty freaking loud. Imagine the scene, and then guess what I did.
I fell asleep.
Several times in fact. I was following this loud, intricate cacophony of sound, and then suddenly I’m in a random dream sequence with the music in it, and then I open my eyes back at the show. I wasn’t tired before the show started, and after the album finished and they played more standard rock songs I was awake and alert again. Why would the most musically complex music I’ve ever heard performed live make me fall asleep sitting up?
Here’s my theory: as a child my parents would play lots of music, including a lot of Zappa. I would be put to bed at 7 or 8 and they would play One Size Fits All among others while I slept, in an old house with thin walls. Has my brain been trained to associate this music with sleep, to the point where it will put me under in a situation otherwise unconducive to sleep?
If anyone has any insight into this sort of phenomenon, please let me know!
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.