Settling In at the New Gig

August 12, 2016 at 11:28 pm in Personal, Tech, Work

I’m nearly two months into my new job. For those of you that haven’t heard, I am a Technical Editor at DigitalOcean, a fantastic startup based in New York City. I work with a great team of people, and I help open-source enthusiasts share their knowledge through written tutorials. I’m responsible for taking their submitted tutorials and testing them out, looking for inaccuracies, security problems, or other issues a reader might encounter. As I work through them, I look for continuity problems, voice, tone, and style issues, and I often help them improve their writing skills.

This is an amazing opportunity for me because I get to teach people through writing, since our community site gets a ton of traffic, and I get to be part of an organization that has core values that directly align with mine. I also get to bring my experience in writing, editing, publication, and teaching to this organization.

Best of all, I get to work with some super smart and genuine people. There’s always someone around with a positive thing to say or knowledge to share.  In previous places, I’ve always been fortunate enough to have that on my team, but it’s been rare to see that throughout the organization.

By the way, our team is hiring. Do you have strong system administration experience and love to help people improve their writing? Come work with me.  And if that’s not for you, DigitalOcean has a few other opportunities as well.

This current opportunity isn’t a software development position. But don’t worry…. I’ve found ways to continue doing software development.

No comments

The Hogan Formula For Software Estimation

July 26, 2015 at 6:20 pm in Tech, Work

Measuring how long a software project will take is a futile endeavor. Unfortunately, people who hire software developers have a habit of asking for the impossible. Like when they want you to build a Facebook clone in 2 weeks for $200.

So to appease my clients and managers over the years, I developed a formula to somewhat accurately address the “how long will it take” question. And despite it being a bit tounge-in-cheek, it’s startlingly accurate when you sit down and think about it.

Here is the formula:

TimeToComplete = (bestGuess * 2) + 1 --> Shift to the next unit of time.

Here’s an example. Someone comes to me and wants me to build a 5 page web site for them. My immediate thought is that building 5 pages of HTML with a Bootstrap theme should take me about 6 hours. That’s based on my experience as a developer over the years. I know I’ll use a bunch of pre-existing things and I know my way around CSS and HTML.
So if I run that through my formula, here’s what I get:

(6 * 2) + 1 = 13 hours --> Shift to next unit of time = 13 days.

It’ll take 13 days to complete this project, according to this formula. Does that make sense? Let’s look.

Day 1: I meet with the client and gather some specific details about the project. It turns out that the client needs 6 pages, not 5, but one of them is a contact form. I’ll be writing a little PHP. Client insists they have all the copy already written for all the pages, and they have photographs. After the meeting, an emergency for another client comes up and I have to deal with that. I can’t spend any more time today working on this project because I’m burned out.

Day 2: I build a mockup of the homepage in HTML with Bootstrap. I then develop a couple additional options. I put a PDF together and I show it to the client by sending an email. I get no reply.

Day 3: I follow up with the client. No reply.

Day 4: It’s Saturday.

Day 5: It’s Sunday.

Day 6: I call the client, since email isn’t working. The client replies that they like the first mockup idea I sent, and wants to proceed with that. I ask for content for the “About” page. They tell me they’ll have their office person send it over. I build out the pages in the template they chose using mocked up content. Productive day.

Day 7: I push the work up to a staging server so the client can play with it. I still don’t have content. I send the URL to the client. They play with it but tell me it doesn’t work on their machine. I test the site in multiple browsers and everything looks fine I head to the client site to see what the issue is with the site. The site comes up fine. They were confused because the text “Lorem Ipsum” was displayed on the page instead of the text they wanted. I ask again about the copy they were going to send over, and they hand me hand-written notes, saying their office person was out of town this week.

Day 8: I key in the content, because I’m nice. I push up the new site. They send me over some photos which I need to adjust to fit. This takes most of the day, but the site is eventually deployed. I get on the phone and walk them through the contact form. They have changes.

Day 9: I’m unable to work on the site much due to other obligations. But I do fix the contact form and ask them to test it.

Day 10: The site is complete, but I’m waiting on final approval from the client. The person in charge has taken a long weekend.

Day 11: It’s Saturday again. But the client does approve the work, with a couple of minor changes. I state that I can make those changes on Monday and I can make it live on Monday.

Day 12: Sunday again.

Day 13: I work through the changes and get on the phone with the client, who says things look great. I put the site live and they use Dwolla to send over a payment. Done.

Does that sound like a realistic scenario?

The problem I’ve found is that developers only think in terms of code. So when you ask “How long will it take to get something done” they immediately drop into “How long would it take to code up an untested first version of something based on what I’ve done before?” As developers, we have to remember that software is 20% code and 80% people. People need time to think about things, they need time to review, and they need time to recover from mistakes or bad choices. We have to factor in vacations, distractions, and many many other things.

Developers love to be a hero with their estimations. I’ve done this. I’ve said “Oh yea that’ll be easy. I’ll just get that done in 10 minutes. And sure enough, two days later I’m still working on it.

Now, in the only-somewhat-fictional scenario I outlined, the client had all their ducks in a row. They paid on time. I didn’t have to work with the ISP to recover their web site password and login information. I didn’t have to deal with people who nitpicked every pixel of the design. All of those things factor in to how long it takes, and all of those have nothing to do with how fast you can write code.

You will have to provide time-based estimates to people who don’t understand software. Do right by them, and yourself, by doing whatever you can to be as honest as possible. Maybe my formula will help you make a more informed decision. Or maybe it can just be a joke between you and your team. Because when you’re talking about a project that would “only take six months” and you’re on year two.

1 comment

Being A Good Critical Friend

January 25, 2015 at 3:58 pm in Teaching, Tech

I’ve been around software development a long time, and a reoccurring theme is to see this kind of feedback from peers:

I’ll never understand the logic behind [some thing I think is dumb / disagree with strongly].

or

If you’re not using [some technology I like] you’re doing it wrong.

Or a variant of

You’re using [some programming technique I think is dumb]? Well I write big applications. [that thing you’re doing] doesn’t [scale / work well / work at all].

This is so common it’s part of our vocabulary now. And I think we say these things without even thinking about how negatively they can affect people.

When I started teaching, I found myself having to constantly give feedback, and I had to learn to do it in a way that would improve the skills of the recipient. And I think that’s what people are trying to do with these kinds of comments. We all have experiences that we want to share. But in the world of 140 character tweets, it’s hard to do that. It’s easy to be unintentially snarky in a tweet, pithy in a pull request comment, or terse in an email.

So strive to get the behavior you’re after instead. By being a good critical friend.

Ask questions that provoke. Provide actionable suggestions. For example:

I notice you used [x instead of y]. I like y because [some amazing thing it lets me do.] You should spend a few hours with it; you’ll be amazed!

That one works because you have experience you can draw from. But it’s only valid if you’ve actually used both. Don’t just shoot down something you’ve never used.You’ll look like a fool. Experienced programmers are pretty smart about figuring out if you know what you’re talking about.

There’s also this angle, which is similar, but more focused on negative side affects:

I notice you’re using [x instead of y]. I did that a few times and it bit me hard. I wouldn’t recommend it because [x,y,z].

See, starting with one of those things contributes to the overall goal; you want to convince them to use your idea, your approach, your methodology.

You could even go farther. It’s never a good idea to assume they have the same situation you do, so why not ask?

I noticed you’re [doing x.] I’ve had problems with that in the past, but I’d love to know why it’s working for you.

or

I’ve never had much luck with [doing x]. What benefits are you getting out of it?

This helps the person fill you in on their situation, if they care to engage in the conversation. It lets them teach you something. And it may help them arrive at a different conclusion by themselves, in a strange form of rubber duck debugging. After all, explaining something is a great way to demonstrate correct understanding of a topic.

The other option is to say nothing. Are they doing something that will destroy the world? Will it make you come in on the weekend to fix it? Or do you just find it irksome? Search yourself for the answers to these questions, and if it really is of no consequence to you or others, let it go. Put your energy into something awesome instead.

We’re all programmers, working in a field that’s so new that nobody really has all the answers. When your convictions or beliefs about something are so strong that you must comment, be a good critical friend to the recipient. They may not choose to listen. But I guarantee you have a much better chance that they will than you do with something that puts them on the defensive or makes them feel stupid. I’ve gotten this wrong in the past. Join with me to be better.

1 comment

How To Derail Your Readers And Students

June 9, 2013 at 5:17 pm in Book, Editing, Language, Teaching, Tech, Writing

There’s no shortage of software developers who are eager to share their passion with others through writing and teaching. It’s an amazing time, and it’s great to have all these resources out there for us to all get better at what we do.

If you’re a software developer who wants to teach others how to do things, listen up, because there’s a chance you’re derailing your students and undermining their confidence before they even get started. In this article I’m going to point out some real quotes and statements I’ve seen that hurt, more than help, the student. And I’m speaking from experience, having done a really good job derailing readers and students by doing these things myself. I’m sharing what doesn’t work, and what does work, in my own experience. I believe that this advice applies not only to people who teach programming, but also to people who write books, articles, and screencasts about programming. By avoiding these things, you’ll create better learning experiences.

#1  Saying “This is really hard.”

If you start off with this one, you’ve already lost people. You’ve demotivated all but the smartest, advanced student. Students want to know they will be successful. Thy need reinforcement from you. They need to know that you’ll guide them through the things that are hard.

Tell them that many people struggle, or that the path will be difficult, but far from impossible. Show them what they’ll be able to accomplish when they’re done. If you’re teaching object-oriented programming, show a before and after example at the beginning of the lesson. Show them the spaghetti code, then show them how much cleaner it will be. Don’t worry about whether or not they’ll “get” what you’re showing. If you take the time to plan what you are showing, your simple example will make sense.

#2 Saying “This is really simple.”

On the other hand, if you tell the students something is simple, you run the risk of derailing novice students who run into errors they caused by themselves. In programming, nothing is simple. A small typo can cause all sorts of trouble for the inexperienced, and then their confidence is undermined. “But she said it would be simple! What am I doing wrong?” And then the learning stops.

You want to avoid “easy”, “simple” and similar words for this reason. You can certainly tell the student that the concept you’re introducing is basic, or introductory, or “the first step.” But keep in mind that everyone starts at a different level. Something as “simple” as declaring a variable has a lot more going on.

#3 Saying “Don’t worry about this right now, we’ll talk about it later.”

This is almost always a sign of impatience on the part of the teacher or author. You want to get to the good stuff, but you’re stuck in some kind of “chicken and egg” situation, so you show something advanced, and promise to explain it to the student later. The problem is that we don’t know when that will be. Be specific. Say “We’ll cover this in a few weeks” or “We’ll get into this topic in detail in chapter 14.”

But more importantly, ask yourself if now is the time to show this to your students. Is there a more simple way you can do something, even if it’s not the “right” way? If you don’t have time to explain the “why”, what is the benefit of introducing the concept at all?

#4 Saying “Don’t worry about this right now, you’ll get it eventually.”

This is similar to the previous one, but it’s a little more problematic because it’s putting the effort entirely on the student to figure it out. Instead, tell the student that they’ll get a lot more practice with the concept. Again, make it clear at the beginning why you’re introducing the concept and how they’ll benefit.

#5 Not Having A Plan

If you’re composing a chapter or a lesson and you don’t have the end in mind before you start, you’re going to be all over the map and your students or readers will be confused. If you’re doing a tutorial, write all the code first, then break it apart, break it down, and explain it. Don’t just write words and throw code samples in. That’s not a tutorial. That’s a reference guide and there’s a big difference. There’s a big difference.

Students need to know the plan at the beginning. They need to know where they’re going and what they’ll be able to do at the end. If you don’t have that plan, how can you convey it to them?

Use mindmapping, use outlines, use some technique that lets you easily figure out what your grand plan is. If you can, start with a “competency-based” approach:

  1. Figure out what you want them to be able to do
  2. Come up with how you will evaluate that they can do it (a test, a project, etc)
  3. Come up with the exercises you’ll have them practice so they can eventually do #2
  4. Fill in the explanations.

This is what’s called “performance based learning” and it’s really effective, but it has to be planned out. Trust me on this – it works so much better than winging it. I’ve done both, and I will always have a plan now, and it will always be based on this order.

#6 Not writing code at the students’ level

If you’re an experienced programmer, and you’ve been through lots of code reviews, you’ve probably developed a style of coding that’s clean, compact, and free of duplication. But if you’re teaching someone how to do something in your language, being terse is going to freak a lot of students out.

When I’m writing examples, I tend to break things into as many statements as I need based on the audience at hand. If I’m writing a book on “Beginning CSS”, I’m not going to write code like this:

border: 1px solid #000;

I’ll write it like this.

border-style: solid;
border-width: 1px;
border-color: #000000;

That is, I’m going to spell out each property, and then I’ll show the condensed version if it makes sense:

If I’m teaching JavaScript, I think this approach is better:

var age;
age = prompt("What is your age?");
age = parseInt(age);

even though I might be tempted to do this:

var age = parseInt(prompt("What is your age?"));

When you’re teaching, you need to explain the meaning of things. I know when the long version is appropriate, and I also know when the short version is appropriate. The students don’t, and it’s my job to get them there.

Silence the voice of your peers that will tell you to refactor your code  Production code is not learning code. Show the cleaned up version later and ask thought-provoking questions about the differences.

#7 – Having out of context, incomplete, irrelevant, or broken examples

Your examples need to work and they need to have context. While some students do just fine with

array = ["a", "b", "c", "d"];

 

Many others don’t. There are many ways that people learn. [1] Try to adapt a bit and use examples in context.

names = ["Ted", "Barney", "Marshall", "Lily", "Robin"];

 

In addition, make sure the code works. Make sure it’s free from syntax errors, and make sure it’s reproducible given the steps you wrote. Nothing frustrates a reader more than trying o follow directions with steps missing. It’s really hard to write tutorials that people can follow. It involves a lot more work than doing it once and writing the steps down.

It’s easy to be teacher-focused and say “Well, they’ll learn from figuring it out.” They’ll learn, alright; they’ll learn that you don’t care about them learning what you’re teaching.

Treat example code like production code; use proper variable names, write it cleanly, and test it every so often. Test not only your code, but the process you’re using to teach it. If the new Android SDK comes out and the new project generators break things, you need to have that in your tutorial too.

#8. Flying Solo

If you’re writing a book, you need an editor. Maybe you don’t need a publisher, but if you’re going it alone you still need a development editor who can look at what you’re doing and help you find the holes. You also need to have your content peer-reviewed. Get feedback from experts, get feedback from readers, get feedback wherever you can get it. You will get better results.Every single person who creates learning material can improve, no matter how long they’ve been at it.

Wrapping Up

The last thing to think about is your conclusion. Don’t just throw a last bit of code out there and jump to the next topic. Recap the concept you’re covering and give the reader or st8dejt t9ke t0 reflect. Metacognition (thinking about thinking) is pretty powerful stuff, and a good closing really helps things stick.

So, all of these things, from avoiding dangerous words, to planning, feedback, and a strong closing, are the things I look for in my own writing, in my own class preparation, and in the writing and course design of others I provide feedback on.

Take some time and reflect on these things. Which of these do you do in your current writing or teaching? What ways can you do better?

Finally, take a look at this passage from an online tutorial about Objective-C:

Pointers can cause a lot of confusion with newcomers to programming or just newcomers to C. It is also not immediately clear to some people how they are useful, but youʼll gradually learn this over time. So, what is a pointer?

[… example omitted….]

Clear as mud? Donʼt sweat it. Pointers are hard – often considered the hardest thing to learn when picking up the C language. Pointers will eventually become second nature to you though, and there will be more on pointers within Objective-C further in this series.

I’m not linking to this tutorial because I don’t want to pick on it too much, but this is one in at least 10 articles and books that I’ve read that bring up this topic of pinters in the first chapter. After reading that, what problems do you see here that could derail a beginner? Are you motivated to keep going? How do you feel after reading that?

Got any other things you think I missed? I’m always interested in improving my own writing and teaching.

[1] http://epltt.coe.uga.edu/index.php?title=Multiple_Intelligences_and_Learning_Styles#The_Eight_Intelligences 

 

1 comment

Things every web developer should know

March 25, 2013 at 8:44 am in Tech, Work

I believe that web developer should have a command of a few simple things in order to tackle the random craziness that web development entails. This isn’t, by any means, a comprehensive list. It is opinionated, but also based on things I see other people I respect demonstrate in their daily work.

JavaScript

It’s everywhere and you can’t avoid it. You also can’t afford to continue the copy-and-paste approaches of the last 15 years. JavaScript is a major component of modern web applications, and no matter how good your C# or Ruby code is you need to know this language well. And it’s an… interesting language. Don’t let its syntax fool you; some things simply do not work as you’d expect. Learn it well, including proper patterns for creating objects, encapsulating code, and handling large numbers.

PHP

I don’t enjoy PHP, but you really should know it well enough to avoid creating chaos. It’s available on nearly every server out there, and it does fit a certain type of application space very well. I’m not going to write a forum or a blog by hand – I’ll use WordPress or phpBB, and at some point I’ll need to know how to customize the behavior or themes which will require PHP knowledge. Also, creating a simple microsite, API, or even a contact form is a pretty simple task that PHP handles quite well.

Basic knowledge of Vim (or emacs)

No, don’t ditch SublimeText or Visual Studio.  I prefer Vim, but I’m not saying you’re terrible for using something else. Here’s the deal though; Vim is available on every platform, and its chief usefulness is editing text files from the Terminal. Whether you host your web pages on a VPS somewhere or on a shared host, knowing how to use Vim (or again, Emacs) to quickly view
and edit files on the server can get you out of a jam. It’s unwise to edit files in production in realtime without testing code or using version control, but sometimes bad things happen and you absolutely need a fix out there now. I’ve used SSH and Vim while on vacation to fix a corrupted web server configuration file that someone else broke, and I’ve used it to quickly change a very bad typo on a public-facing web page while at the mall. Seriously, look into learning one of thse tools.

Understand Basic SSH, SCP, and Public Key

In order to easily edit files on your server with a text editor like Vim, you’ve got to know how SSH works, and in order to do it securely, you need to understand public key authentication. That’s where you generate a public key and a private key on your computer and then give the public key to the servers in which you want to log in. This extra layer of security is crucial for modern sites.

If you’re using FTP to transfer files, look into SFTP, the secure FTP protocol often available if you’re using SSH. It can also use public key authentication. And if you’re interested in copying multiple files from your machine to your servers, look at SCP, or Secure Copy. It’s a great simple command-line method for moving files around.

$ scp -R public_html username@server:/var/www/html

Honorable Mention: Node.JS

JavaScript runs on the server-side now, thanks to Node.JS, and a lot of developer tools are showing up. For example, testing tools, concatenation and minification tools for CSS and JavaScript, and even tools that reload your browser when you make changes are all written in Node.JS. Tools like Grunt make it easy to create a sophisticated build and test environment for your projects, and if you install Node.JS you can also take advantage of CoffeeScript.

So that’s my basic rundown. As for me, I personally can’t do web development without CoffeeScript or Sass, but those aren’t necessary for everyone to know. Share your thoughts.

1 comment