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’ve been made an interesting offer by Nest – they will give me one of their spectacular thermostats (and a smoke / CO detector), if I can find a fun open-source use of their API and write it up.
I already explained that I’m not a programmer, although I’ve been experimenting with python for the last couple of weeks, but I’ll happily give it a shot.
Step 1: Brainstorming.
What would I want to build to extend the functionality of a wifi-connected smart thermostat? The first thing that comes to mind is making a twitter account for it, and having it tweet the temperature in my home. I figure’d that would have been done so many times before that there would be nothing left to create, but a quick google search told me that was not the case.
What else? Well, I have a promo code for Twillio, and Nest’s API has functions for smoke and CO detection. I see an opportunity to create an alert to my phone if there’s an emergency at home. If the detector is downstairs, I’d rather it call the phone on my nightstand then sound an alarm where it is.
Do you, the avid reader, have any suggestions? What would you want your thermostat to do for you?
From now through Sunday I’ll be at Pennapps with Linode, giving out swag, Linode credit, and mentoring where I can! I may also try to do some hacking myself, but I’m not sure if I should be reorganizing my services across different servers, or working on a new project.
These hackathons run 48 hours straight, but I don’t know how long I’ll last. I’ll try to update here as the hours pass.
EDIT: This is what I’ve come up with so far: Python Prime Number Generator
EDIT #2: I’ve made another couple of useless site: GET SCHWIFTY! and MR MEESEEKS
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.
Hello, avid reader! (Don’t question the adjective, let a man dream). The good news is that I’m back up and running with a site that’s more than just HTML edited in nano. The bad news is that my older posts are probably not coming back. I may be able to recover the text from a backup somewhere and manually re-import them, but no one should hold their breath over it.
As I type this, my coworker and I are entering the dreary early morning hours of a hackathon in Brooklyn, where we are stationed as mentors. My personal hacking has been the recreation of this blog, and installing CyanogenMod on my phone.
The Red Bull is calling out to me, but with the Starbucks and Monster already coursing through my veins, I’m saving it until I start to nod off, in the hopes that I’ll make it through to the judging and still be sane enough to choose a worthy winner for our sponsor prize.
The following hours will probably be filled with further CMS and ROM tweaks, while fighting the sweet embrace of sleep that seeks to pull me away from my duties and into the warmth of nothingness. Toodles!