On Publishing and Writing and Documenting


I was telling my daughter just the other day that it is important to know how to spell, and just as important to know how to write (and write well). She’s going into 5th grade, so such a lecture may be a bit premature. No worries. This lecture will be a repetitive one.

As I recall, the conversation came up because I was telling her how impressed I was that she was reading a book just for fun on her summer break. Reading–reading real books by real authors with real editors–is the best way to learn the craft. And for whatever reason, it seems that fiction is the best place to learn to write. The technical stuff–most of it–is dry and full of poor writing.

I love fiction. Shouldn’t we all? I read much more fiction than non. It would be easy to argue that the skills used to convey well-written fiction have little if any crossover into a technical career. Don’t say it! (If you already said it, take it back!)

Reading quality fiction is applicable to any professional career, and its application comes in a form of learning requiring little deliberate uptake. So long as a story holds my attention, reading is easy and fun, and the learning and improving of grammar is a secondary osmotic benefit. While lost in a great story, we build upon vocabulary and command of language. We see styles and methods that we like. These we recall. We see styles that seem awkward or boring. These we recall as well (and avoid).

I cannot name a single professional career in which the ability to write is of importance. It may sound absurd, as though I am telling you that simple arithmetic is important. But if this is such an obvious assertion, why do we all see so many loud and proud communications written with bold indifference toward basic English?

Lest I get too far ahead of myself, I should come clean with something. The other day sent my boss a very short email, typed on my iPhone, as I hurried to get things situated at home. The email, I thought, was short and to the point:

Running a little late this morning. In by 9:30.

(Micky is not my boss’s actual name, for the record.) The text above is what I meant to write. It is not what was sent. When I arrived to work, “a little late,” as I had told my boss, he had already had a good laugh at my email. Here’s what I actually wrote:

Micky-- Rubbing a little late this morning. In by 9:30.

Rubbing. There it was… In my boss’s inbox forever. Foiled by autocorrect again!

Autocorrect is great for very short things, but only when used with caution. In this case it wasn’t a big deal (or was it?). Aside from the hilarity, my boss knew what I meant to write, and he guessed that autocorrect created the error. As silly as this example may be, it does leave a certain aftertaste, does it not? I’m a technical person, paid for focus and attention to detail. I write software… Software that needs to work the right way every time. While the example above is chuckle-worthy, it is also cringe-worthy. I know better!



Publishing articles here and there has been fun. There’s something extremely satisfying about seeing your own name in print. (See how I used two adjectives in that last sentence? Don’t do that in a technical document. Ever.) Not to mentioned a certain thrill in having your words read by an audience. But with this comes a great amount of work and time commitment, which I haven’t  exactly had the bandwidth for. To be sure, writing an article for a trade publication must be a labor of love, as they payout for such things is right around $0.00. 

It isn’t all that difficult to get an article published, and it may be something worth seeking if not regularly, at least once. The key is simply to have a specific goal for the article and a certain amount of knowledge of the subject (along with a willingness to put in some research where necessary). When it comes to publishing in a trade publication or website, it is also important to spend time self editing. Most of these publications, I have found, don’t edit much. It is embarrassing to see a typo make its way through. Even worse, reading a sentence or entire paragraph that you wish you had revised can be infuriating.

Infuriating may be a strong word… Or not. Personally, when reading anything, be it a book, article, or blog post, I lose focus and interest annoyed by an author’s lack of writing skill. And while I am fairly confident that even this post will have a sentence or two that should be reworked, I stand by this assertion!

Keep the grammar simple. If you aren’t sure whether a particular sentence structure works, don’t use it. Lofty language is for poets, not for those of us attempting to convey a point. If a may set aside humility for a moment, the most consistently positive feedback I’ve received over the years has been with regard to my ability to write. What’s the secret here? Nothing, really, at least not that I can pinpoint. (See what I did there? I used a fragment. I love fragments.)

A few things:

  • The developer that actually takes the time to document, from commenting code to precise checkin comments to keeping the wiki clean, already has a leg up.
  • Don’t write to impress. Chances are you will fail. Write to communicate.
  • Keep it simple, grammatically clean, and to the point. As I mentioned before, if you believe something doesn’t make sense, rewrite it in a way that you would like to read it. 
  • Semicolons suck. Too strong? Okay, find. Semicolons are way overused! This doesn’t have much to do with technical documentation, per se. I just couldn’t help but editorialize a bit.

I am hitting the Publish button now. I have no re-read or edited this post. Shame on me!

Some Random Links

Swift – Not really new news by now, but I’m looking forward to having some time to tinker with it.

Chordify – Give it an mp3 or URL, see chords, play along. Really cool.

Oracle vs. Google vs. Java – This is still going on?

Why Choose Jenkins (over Hudson)

Browser Usage Statisics — Chrome is clearly in the lead. So why do we all continue to bend over backward to support Internet Explorer quirks? Probably because so many corporations insist on it.


Moore’s Law Plateauing? — While I’m skeptical, do people really pay that much attention to processor speed any more? Increasing persistent storage speed along with the leaps forward from SSD seems to be our greatest performance gain these days… If the cost ever comes down.

Patent Troll Targeting Podcasts — Why isn’t this getting more attention?

What’s The Value of College?

CNN: Surging College Tuition
CNN: Surging college costs price out middle class

Not long ago I found myself working alongside a brilliant college dropout–A young junior programmer who was just plain gifted when it came to software development. I was very surprised that he hadn’t completed a degree of any kind. It made me wonder why I had, without much consideration, put such high value on a four-year degree.

A recent InfoWorld article, 15 hot programming trends — and 15 going cold, touches on the issue of rising tuition costs and the questionable value that they bring.

I attended Ball State University — a place hardly known for being an engineering college. It was a nearby school with a Computer Science program that did not cost as much as IU or Purdue. For someone like me, it was attainable. While I enjoyed my time at Ball State, and I learned much, very little of my Computer Science education turned out to be directly applicable to my career. Sure, I learned formal concepts, design practices and perhaps a little about requirements gathering and QA (very little). Some of what I thought I knew had to be unlearned, as I came to realize that things operate differently in the “real world.”

Ultimately, as someone with an inherent interest in writing software, I suspect that everything I really needed to know could have been learned in a year of dedicated study. The rest comes from workplace experience.

The problem, of course, is that if I hadn’t gone the college route, spending 4+ years working on a Bachelor’s degree, I would never have been able to land my first job interview. And it was that first job where I really learned how all this stuff that I knew really came together in a real business environment on a project of significant size.

Through the years, I’ve met great, good and awful software engineers with varying backgrounds and educations. Many of the best software developers attended college, but graduated with a degree in something unrelated (History, Art, New Testament Studies, English, to name a few). These people gravitated to Software Engineering and Development through various means, some of them going on to pursue certifications and other training.

My experience hardly reflects any kind of comprehensive analysis, but I don’t hesitate to say that most of the software engineers with undergraduate degrees in non-CS fields are among those that I consider excellent.

There was a time, not all that long ago, when droves of students gravitated to Computer Science because they heard that it was a great career to pursue. While I happen to agree that it is a great career, I don’t think it is a career for just anyone. It requires a certain type of interest and motivation. Perhaps it is because some folks enter Computer Science undergraduate programs for the wrong reasons, but I have observed all ranges of skill level from those with CS backgrounds. I’ve found myself shocked (more than a few times) by the poor quality of code created by developers with formal CS educations. I once was asked to help debug some code written by a colleague that had compilation problems. It didn’t take long to find the problme: A 2,000+ lines-of-code function that caused the compiler to choke.

Doctors, Teachers, Lawyers, Accountants–These are all people who require specific degrees and certifications. I know that I don’t want to have my eyes checked by a self-trained Optometrist. In software fields it is different. After a software engineer has some experience, it seems that his or her degree becomes afterthought. Unless the subject of college comes up during a lunch conversation, rarely do I actually know the formal education or degree of a colleague. What I do know is that person’s quality and volume of work. Don’t get me wrong–there are things that may be taught in a Computer Science department that are absolutely necessary. Knowledge of algorithms and design patterns is important. It should be noted, however, that knowledge and application are different beasts.

I wonder–If college costs keep rising at such a staggering rate, at what point does the return on investment lose its worth? With companies hard pressed to find good software engineers, and with a greater percentage of the population unable to afford a 4 year degree at even a semi-respected university, when will the traditional model change? There are so many options–from certifications to local technical schools that are available at a fraction of the cost. At some point it seems that a college degree becomes more of a social status symbol than a true reflection of one’s talent or ability.

We’ll have to begin to ask ourselves: Which candidate is right for the job? Is it the one fresh out of college with a CS degree and a 3.8 GPA who lacks experience working with others on a project of scale, or is it the non-college-route self-taught programmer who has proven talent that can be seen by way of open-source contributions?

Occasionally I have seen job postings for software engineers which claim to require a Master’s Degree in Computer Science. I have to wonder: What does the hiring manager believe he or she might get from the engineer with a Master’s Degree that differs from the engineer with a lowly Bachelor’s Degree? In my experience, most Master’s Programs a little more than the same programs that undergraduates complete… The only difference is that the students in the program have already completed a four-year degree (and that degree could be anything).

This isn’t to demean formal education. If I had it to do over, I wouldn’t change my time at Ball State University. No way! I was fortunate, however. When I went to Ball State, college was merely ridiculously expensive. Today it is insanely expensive. In 10 years, it will be unattainably expensive. When that happens, where will the software engineers come from?

High Output = High Output of Defects Too (So go easy on ‘em!)

ImageWe all know that software defects are pretty much inevitable. (Right?)

A bad developer may produce a fraction as many defects of a great developer. I’m guessing Linux Torvalds has written more bugs that I could write in my entire career… And yet, to say that this means I am a better software developer would be absurd.

Inherent in this fact is an easy truth to understand but a difficult truth to respond to: The developer with lower output of overall contribution likely has a lower volume of defects tied to his or her name (or commits), while the superstar developer may be put in that less-than-fun situation of accepting responsibility for a defect a little more frequently than anyone would like.

The obvious reason for this is the simple fact that with great output of success comes a greater output of defects (even though, percentage-wise, the great developer may create significantly fewer). A less obvious reason for this is that the great developer–the super-talented one whose volume of output is consistently astonishing–is much more isolated from peer-review of other teammates. Those who don’t understand or work at a pace behind that of the great developer are less apt to offer insightful peer review. Also, the most talented developer on the team may be the most demanded upon (and when we believe in Software Ninjas, we’re setting ourselves up for problems).

There may be good reason to go easy on the guy or gal who must humbly own up to that defect that made its way into production. If fingers must be pointed, its the entire time that should be reviewing the work of their peers.

SSH User Annoyance & Solution

I’m in an environment where whenever I ssh to a machine I have a different username than that of my main machine. For example, the username on my desktop of “Some.Desktop.User,” whereas all the Linux environments I ssh to use the username “Some.Linux.User.” I’ve typed “ssh <host>” countless times, only to be annoyed when I realize that the password I am being prompted for is for “Some.Linux.User,” which does not exist on the host. Of course I should have typed “ssh <host> -l Some.Linux.User.”

To make life a little easier, do this:

In ~/.ssh create a file named config. In that file add the following:

Host *
User Some.Linux.User

Likewise, if you have a number of different accounts on different servers, you can do something like this:

Host servername.domain
User Some.Linux.User.1

Not exactly a super secret tip, but a useful time saver.

Obligatory Social Media Advice to the ‘Younguns”

Social-Media-IconsI’ve seen a few good posts and articles that make attempts to explain to young ladies—teens and preteens—the consequences of their posts online. Many of these are very good, with many great points. This is my own attempt. Don’t get me wrong: I love social media. I’m a fan.

Thirteen to eighteen can be strange years of life—this is nothing new. What is new is the technology available, and the way that a single poor choice can do to ruin a reputation. During these years, kids have the ability and know-how to make choices with lasting consequences. They do not always have the wisdom that should be used with such powerful, lasting tools at hand.

I remember being a teenager. (There I go… I sound old with one short sentence.) It wasn’t THAT long ago! I also remember saying things like, “I don’t care what people think about me!” and “As long as I’m true to myself, that should be all that matters.” Neither such statement is, was, or has ever been true. Every teenager who has ever said such things (most of them) thinks he or she is the first one to come up with such an idea. Also, every teenager who ever said this actually does care what others think.

It doesn’t change in adulthood. I care what others think of me. You bet I do! I care what my boss, my family, my neighbors, and my colleagues think about me. Why wouldn’t I? I want them to think that I am loyal, hard working, and kind. Heck, I want them to think that I am smart and handsome! I may be neither, but the desire is certainly there.

While it is important that we don’t allow unfair criticism to impact our personal values and sense of self worth, there is always good reason to take heed of what others may think: Reputation.

I have daughters—not quite to the age where this is yet a problem—but its coming, and its coming very soon. Unlike many parents, I’m fortunate enough to be tech savvy. On the computers in my house, and on my wi-fi, there will be little if anything that goes on without my knowledge. I know how to block certain sites and how to track access. I know how to obtain passwords. Will I snoop on my daughters? You bet I will!

I’m also up on the current trends, so I guess I’m lucky enough to know all about Twitter, Instagram, Snapchat, and Vine and Ask.fm. Not long ago I set up an Ask.fm account to see what it was all about. I was bothered—repulsed, actually–by the creepiness of it. If ever there was a tool to allow strange folks with malicious motives to stalk young people, this is it.

In our house my wife and I have established a rule, and to be fair (at least in the eyes of naïve children), this rule will work both ways: No password are to be hidden from one-another. Other than surprises–i.e. gifts–there is never a good reason to keep secrets from immediate family. Sure, they’re young, but it is important to establish such rules early on. Dropping a new rule on a kid when he or she turns a certain age is not likely to go over very well.

To some this may seem like an extreme move. Even the most involved parents that I know sometimes say that children need their privacy. I certainly agree that I don’t need to be breathing down their necks at every turn (nor could I). When it comes to one’s online presence, however, this is necessary. Too many parents have no idea what their kids are doing on the phones, iPods, or tablets that they received for Christmas. Some think that simply disallowing Facebook and Twitter accounts is sufficient, without knowing that the kids have already moved away from these social networks in favor of others that the parents aren’t hip to.

I’m not foolish (well, not always).  Monitoring devices and network access is far from foolproof. At some point there will be nothing I can do to ensure that my children aren’t doing something stupid by way of social networks or text messages. The best I can do is explain the possible consequences and teach them to be smart, safe, and be aware of their reputation.

I’m not the first, nor will I be the last, to say this: A single picture, a single bad text message, or a single bad post can do much to solidify one’s reputation. It can do a great deal to lock in the type of person you are perceived to be—And perception is everything! The unfortunate thing about a reputation is that the negative is much more easily locked in by a few bad choices, while it takes much diligence to maintain a good reputation. We’ve all made bad decisions, but until recently, such bad decisions weren’t so easily disseminated to the masses.

Others have probably heard this advice: Before posting or sending something, ask yourself, “Is this something I would want my grandmother to see?” (Or how about “Would I want my teacher to see this?” There’s a good chance—a VERY good chance—that one of your teachers will see it.)

The above is good advice. Great advice, actually. Unfortunately, most teenagers aren’t thinking of this question as a prompt of appropriateness. They are thinking of the near-term benefits, along with the perception that the “old people” are clueless (old, in their minds, being anyone over the age of 25). (I’ll say it again: If your parents don’t, your teachers can and will see your posts.)

As I peruse Instagram, I am sometimes stunned by the amount of junk that kids post, and the lack of any self-filtering used. In the case of young ladies, it seems that many of them are eager to get likes on their pictures, as they try their best to look attractive and appeal to the boys at their schools.

The duck-lipped-smoochie faces are everywhere. The bikini-selfies, posted with some sort of idea that, while a young lady just happens to be wearing her swimsuit, she really just wanted to post a picture of where she was at—or her new hairstyle—or a new gadget is not the exception. It is the norm. I suspect that many such pictures are posted with the idea that plausible deniability is along the lines of, “Oh, I didn’t realize people would see it that way.” (Yeah, right.) Maybe its true. Maybe the ever-trusting mother will say, “Oh honey, you didn’t know better, but some people may see that the wrong way.”

Here comes the standard disclaimer (I tried not to, but alas, I must): I’m not a prude, but…

What? You don’t believe me? I’m not a prude! Really!

Many, many people—countless more than a kid can imagine—see these pictures. It doesn’t matter what privacy settings may happen to be. Any image can be copied and passed along. I’m reminded of how infuriated Tommy Lee and Pamela Anderson were when their now-famous home video became public. The best way to avoid having it ever seen would have been to not create it in the first place.

With social media, the situation is a little different. The people posting these pictures want them to be seen, at least by some audience. As we all know, however, when it comes to anything on the Internet (including text messages), no such posts will ever be as private as one may hope. I’m sure that telling teenagers to refrain from instant messaging isn’t very easy these days. And even the best, most involved parent cannot look over a kid’s shoulder all day long.

Anyway, here are a few things I would like to point out to any young ladies who may happen across this post. I could say all the things that any of us heard growing up: Trust me, I’ve been there…, I know more than you think I know…, Adults aren’t as stupid as you think…, This is for your own good…, What would (insert relative’s name here) think of that picture?

I hope, for the sake of my own children and for the sake of others, that some amount of this advice becomes commonplace enough that tweens and teens begin to take heed.

Nothing is Private

I know that you think you and your boyfriend will be together forever. You won’t be. When you break up, do you really want him to have that picture you sent? If he does have any such pictures, you can be fairly certain that all of his friends do as well. If he hasn’t passed the picture along to his buddies, he will when the two of you break up.

That picture you sent to the love of your life a year ago will go viral. Maybe not to the degree of Charlie Bit My Finger, but to a much greater degree than you ever imagined or desired.

The Grandma Test

Here’s a better question to ask yourself, even better than asking if you’d want your grandmother to see it: Would you want your future husband and children to see it? Long after middle school and high school, after all the silly mistakes that we make along the way, and after those blunders (you hope) are forgotten, the Internet doesn’t forget. You can try to delete your accounts and remove old posts, but it’s all backed up and cached somewhere. More importantly, you cannot delete the accounts and posts of others. Once that picture or video you sent is out of your hands, it’s out of your hands for good. Sometimes you’ll be on a job interview. Do you really want to wonder if a potential employer happened across that thing from years ago? (Employers Google candidates. Its true. They do.)

You know what you’re doing–Admit it!

You posted a picture of yourself with the caption “I love my new hairstyle!” It just “so happened” that you were standing braless, or in a bikini, when you posted that picture. Maybe 2 guys from your school pressed the like button. Maybe 10. Maybe 100. You’re secretly thrilled, because you know—admit it—that they aren’t liking your hair. Teenage boys can be vile, filthy creatures. On this I will say it without reservation: TRUST ME!

Now that you have posted the picture, for all to see, and you got a like from Billy Smith, that cute guy in your math class, you may have some sense of pride. This is what you were seeking in the first place, right?

What if Billy asks you to the semiformal dance? You are going to meet his parents—His mom and dad, maybe even grandparents—who may or may not have their own Instagram accounts (or maybe they check his phone messages—and maybe he doesn’t even know it). Do you really want his mother’s first and only impression of you to be as that girl who posts and sends provocative pictures of herself? I’m sure the duck-lips that you made while taking the picture will be the least of her concerns.

As for Billy, what are his thoughts about you? Is he someone who likes you because you are funny, pretty, and charming? Or has Billy gotten the idea that you’re exactly the kind of girl who is going to satisfy his teenage-boy urges?

Billy will never admit it, but he’s thinking of pretty much one thing and one thing only. I’ll let you in in case I’m being too vague: Billy thinks that any girl who would post a picture of herself wearing next to nothing, and get away with it, probably has parents who will allow her to stay out late and do whatever. And Billy is fairly certain that his semiformal date has pretty much already said yes to his planned advances.

Maybe you’re okay with Billy having such ideas. Maybe that’s the kind of young lady you are. If you aren’t my daughter, it isn’t my place to scold you. But what if you aren’t ok with this? What if you’re just a young lady who, like most teenagers, wants to know that she’s pretty. And maybe that bikini pose that resulted in100 likes on Instagram provide that kind of boost to your self-esteem.

I’m not ridiculing you. We all want to be liked. We all want to be attractive! I love it when I post a family picture on Facebook and someone comments, “What a great looking family!” I’m no different. There’s a certain satisfaction in being complimented in such a way.

→ Back to Haunt

Here’s another question: How is your self esteem going to be when Billy dumps you a few days later, and shares that private picture you sent to him while getting ready for the dance to all of his friends? (Hint: It’s going to be in bad shape.)

Or what if Billy turns out to be a downright nasty dude, far worse than you could have imagined, and he follows up with a comment on that Instagram picture you posted with a detailed account of what happened after your dance? It could be all lies, but the people seeing such words along with a promiscuous picture are going to assume that its all true. Even before you have a chance to delete his awful comment, it has already been seen by your friends, family, and others. This is far from embarrassing—It’s devastating.

“But Billy would never do such a thing!”

Are you sure?

The Creeps

Let’s not forget about the creepy old men out there. It’s tragic, but true. There are some very bad people in the world, and your lack of experience may lead you to a strange conversation. You’re young. You assume the best. Maybe those kind messages you received lead you to go meet this guy. He told you he’s in college, and that he just turned 19. He even sent some pictures to prove it! Yikes. This goes beyond ruining your reputation. It could ruin your life. It could wreck a family. I’m not trying to play up the possibilities for the sake of creating some worst-case, only-in-the-movies scenario. The reality here is frightening enough. Don’t ever so much as even consider meeting someone in person who solicited you on the Internet. Please.


Finally, bullying. I’ve seen it myself, and sometimes from surprising sources. It might seem funny to post a picture of that zit-faced nerd from you biology class. Maybe the number of comments you get from such a post, along with the “hilarious” comments, offers some sort of thrill. It puts you on a pedestal, somehow bumping you up a bit on the cruel social ladder of high school. You’re way-cool. You’re in the cool crowd! You’re social status has put you in a position of high-school pecking order above the nerds! I could go on and on about bullying. There’s something about the detachment of a post that makes those who wouldn’t typically bully in-person behave much differently. It makes bullying easy, but no less cruel.

That nerd, he’s a real person with real emotions. He’s more than a hash-tag. He’s seen the post, and now we must suffer through all the hurtful comments. His offense? Nothing that he ever had any control over. Maybe he already felt bad enough about the crummy clothes he has to wear. Maybe his family cannot afford anything better than thrift store purchases. Maybe his mother passed away, and his father is doing the best he can, and the nerd, let’s call him Jimmy, has enough difficulty in his life without being publicly ridiculed for little more than not fitting in.

Is the emotional dismantling of Jimmy something that you want to be a part of? You may not realize it yet. You won’t know if for years to come, but that boy you made fun of may turn out to be the best marriage material out there. Jimmy-the-nerd may turn out to be the nicest young man you never knew. Be nice to Jimmy. Sit with him at lunch. He may turn out to be an amazing young man.


I know all of this sounds a bit surly. It probably even sounds like the foolish voice of some “old guy” who doesn’t get it. It’s worth saying, in any case. Apologies for targeting the females out there. All of the above advice is equally appropriate for you men, but I’m a father with daughters.