Posted on: Thursday July 10, 2014
A couple of years ago, Tom Preston-Werner wrote a blog post about writing your README first. The basic premise was simple. Before you write any code, write down how it will work. Detail all of your documentation, and then once you have a solid understanding about how your library will work, you then drop back and write the code.
It was quite popular, and a lot of developers loved the article. It solved two problems. First, it provided a solid way to provide documentation for users of your library. Second, it provided an opportunity to find and think through possible solutions before they were programmed.
On the complete opposite side of this issue, Joel Spolsky wrote a blog post about creating highly detailed functional specs.
Joel stated that without all the details formally documented, a developer can't possibly know what to build. There are just too many questions that need to be answered, and these questions are easier to answer in a detailed text document.
Joel goes so far as to say that no code is written at Fog Creek Software without a spec.
I think there is some room between the two of these. There is a sweet spot between a README for a library and a fully detailed document for an application.
Before I dive into what I think the sweet spot is, let's define what a functional spec is.
A functional spec is document that details all of the user flows of an software application. It goes way beyond just documenting how an app works. It goes into great detail about every possible item in the application. Generally, these documents have wireframes and screenshots of the user interface. A functional spec might go so far as to have personas and scenarios.
The knock on full fledged functional specs is that you can't possibly know everything up front. These specs are directly tied to waterfall. The idea is that a product manager creates these documents and "hands them over the wall" to the developers, who then strictly follow them.
The problem with this method is change. As developers learn about the application while developing it, it becomes difficult to add features based on new knowledge because the manager has spent several hours detailing everything.
Joel really goes into detail in his blog series. He makes some great points and has me about 80% convinced that these documents are quite useful.
My problem is that most of these specs go too far.
When Tom described the process of documenting your library or project with a README first, he referenced the fact that we lost something between functional specs and agile practices.
Tom targeted libraries and projects specifically, I tried it out and thought it was great, but I don't write a lot of libraries. I write lots of applications, and in a true agile mindset, documentation before code is evil. So I kinda forgot about it and moved on.
But these types of documents do work with software applications regardless of type. It's super helpful to think through views and features and document how all of that will work.
This leads right into TDD. Something gets lost with user stories. They typically lose context, even with the given when then syntax.
The Sweet Spot
Okay, so if we have these monster documents that are created in a word processor by some manager and then we have simple text files created by developers, where do they meet in the middle.
Well, the word spec has a bad connotation with it. Traditionalists think of these docs as final and agilists run from them like the plague.
What about guide? What if these docs were not final spec, but guides. Maybe these docs just state based on what we know right now, this is how the application will work. The guide then becomes more of a minimum set of features and screens. And it's easier to change a guide. No one feels bad about updating a simple guide that doesn't have three full days worth of work attached to it.
The Functional Guide
So, this is it. I think a Functional Guide is what serves me best. I can take everything from Readme Driven Development and some aspects from Functional Specs and create a hybrid.
The format depends on the audience. If it's developers, then it should absolutely be a README. If you use markdown, you can add images of wireframes, sketches, or whatever else you need to communicate. Plus, it's diffable in Git. You can update the doc as you build out new features and deploy the new README with the branch you are working on. It just becomes part of the refactoring process.
If your audience isn't developers, then maybe a formal document makes more sense. Something interchangeable, like a PDF. It becomes a little harder to track changes, but it's certainly possible.
In the end, this is really about thinking. Thinking about the users of the software. How will they interact? What is the best flow for them to complete a job? In fact, what jobs need to be done?
One last point. If you've ever been the newest team member, you'll know that it can be really difficult to get up to speed on a project. It would be incredibly useful to have a document that you could look through that detailed the thoughts behind some of the decisions that were made. Bonus points for being able to go through the history of that document.
And finally, I'm just finding what works for me. Maybe this is totally insane to you. I don't know. Maybe your brain is wired differently from mine. I know that when I sit and start typing out how an app should work, it opens a lot of door to ideas that I know I wouldn't have thought of before.
Give it a shot. See what you think.
I'd love to hear your thoughts on what works for you. If you don't mind, send me an email at email@example.com and share your experience.
Posted on: Thursday June 05, 2014
I'm not sure where the conversation started this time, but it has come up again. Someone on the Internet assumes that being able to code is all there is to building apps. That as long as a person can code, that's all they need.
And in fact, they could just find anyone that knows how to code, tell them what to do, and off they go punching keys and writing code.
Obviously, nothing could be further from the truth. Programming is such a small piece of the puzzle.
Dave makes some really great points. I want to touch on a few of them.
An Immature Industry
Dave says that he is frustrated with the term coder because it seems to go over our head. That it misses some very important parts of our industry, noting leadership and developing new talent. He says that this is due to an immature industry.
I'm not sure I think it goes over our head. I think it's simply ignorance and a lack of effort to understand how software systems are built; web, mobile, or otherwise. To blanket us as coders simply gives someone that doesn't understand our industry and is too lazy to try a blanket term to use. I think this is because they don't understand. The equivalent of saying I'm not good with computers. Lack of effort.
Dave also jokes about calling a reporter a keypresser, making the comparison that minimizing the software industry down to someone sitting in a chair entering text into a text editor, is no different from saying a reporter just presses keys.
I agree with Dave, but I don't think this gets us anywhere. This just gives the other industry (the lazy one bundling us as coders) a reason to shrug us off.
But I don't know a better solution. I guess it's education. But that raises another problem. If someone is too lazy to bother researching how software is built, they surely won't bother reading or watching what we produce to help educate them. Although, it's probably still worthwhile.
Dave and I agree that developer is the best term. It fits what I do when building software. It's not just programming. It's thinking, designing (visually and architecturally), and then programming. To have an idea for something and take it from an initial thought to a finished product. Programming is such a small part of that.
The Art of Building Software
The problem I have with this programmer/coder talk is that it boils it down to a commodity. It's not longer a craft or an art. It's just an activity. I feel it attempts to reduce it to a statement like Take a few classes and you too can be a coder. It's easy.
I prefer the creator route. That's how I started. I didn't even know I wanted to be a developer. I just wanted to build stuff on the web and it just kinda grew organically with each step.
Posted on: Tuesday June 03, 2014
Got The First One Done.
A lot of questions were floating around in my head as I gave my first conference talk about teaching programmers. Would anyone show? Does anyone care about my topic? How bad will I fail?
It was scary, but my expectations were just about where I wanted them. Actually, Self Conference was probably the perfect conference for me to cut my teeth on. Small enough to be semi-comfortable, but large enough to have plenty of strangers.
I presented on Teaching Programmers Through Empathy. Really I wished I would have called it Teaching Programmers Through Experience, but I still think it went rather well. If you attended, I would love to hear what you thought. Shoot me an email at firstname.lastname@example.org and let me know what you liked and disliked.
Talks are great and all, but it's what happens after it's done that really matters. At the end of the talk, I took a few questions. To my surprise, there were about 5 people interested enough to ask questions. But that wasn't the coolest part. The coolest part was the dialogue. The attendees started to talk with each other and answer each other's questions with their own experiences.
This dialogue was especially sweet because it's part of what I presented on. Open dialogue and collaboration. I don't know if it's related, but I think I'll hold onto the thought that it was.
What I Learned
I was pretty worried about interest in learning how to teach programmers. I know code schools are doing well. And I know other forms of teaching like apprenticeships and bootcamps are also doing well. What I didn't know was if anyone is thinking about the environments these things are taught in. To take that further, I didn't know if anyone cared about what comes next.
I think we are ready for the next steps. I think more programmers are asking themselves what comes after code schools. Have code schools peaked? What else can we do? How can we make it better?
I'm looking forward to answering these questions and exploring options. With any luck, some conference will allow me to talk about what's next.
Speaking in Public is a Craft
You never forget how to speak in public, but you sure lose your mojo. When I taught a class every weeks, I was pretty good at speaking in front on people. Granted, it was a lot of the same people most of the time. But I got pretty comfortable and I even liked it a little.
I definitely lost that comfort. I'm looking to practice a lot more and see if I can grow speaking into something. It's definitely a challenge, and who doesn't like a challenge.
Posted on: Sunday June 01, 2014
I gave my first conference talk on May 30th at Self Conference. I presented on teaching programmers. I touched on four topics.
- Safety. Creating a safe learning environment is huge. I went over what this means and some techniques to use.
- Authority. Authority is all about becoming a reliable resource. I also touched on some techniques here.
- Collaborative Learning. I probably spent the most time on this. It's so important.
- Mentorship. I closed out talking about how you continue to teach after the course is over.
It went pretty well, and I think creating an effective environment for teaching is a great topic. Something we should definitely should be talking about more.
Remember , We Are All Educators
Posted on: Friday April 25, 2014
I have had this issue for a few years regarding conferences. The issue is that I think, at a certain point, a person passes from listening to teaching. A sort of enlightening moment. After so many talks, I think most people start to wonder if they should be speaking.
I thought that was the case with me and made it a goal in 2014 to start speaking at conferences. I had no idea what I would present. Just that I wanted to give it a shot.
When selfconference came around asking for speaking submissions, I thought I would give it a shot. And for some strange reason I thought about sharing my experiences teaching programmers with little to no experience how to program. This would be pretty easy for me. I'm basing this off of my own personal experience, with some lower level concepts mixed in.
My talk is titled Teaching Programmers Through Empathy and is a walk through some of the things I've learned, some of the concepts I've used to teach in that setting and of course some of the failures I've had.
I'm not super qualified to talk about this subject. I don't have some teaching degree. I just have a two-year business degree and some University credits towards teaching in a technical setting. Even then, I didn't finish the University degree. I came close (who doesn't), but I did not finish.
It sure was rough in the beginning, but I caught my stride after the first year. Teaching someone a programming language when they don't understand programming logic is challenging. But you start to find signs to look for to know if you've gone too far.
So What's in the Talk?
From the Abstract:
There is a saying that those that can’t do, teach. Nothing could be further from the truth. In fact, teaching may be one of the more difficult things you can do as a programmer. Once you start to think about how to explain complex topics to a beginner, you start to realize how far you’ve come and how difficult it is to explain what you know.
In this talk, I will share my experience teaching web development to those that have little to no prior experience. Topics include creating and maintaining a safe learning environment, using real examples to make concepts more concrete, and teaching how to learn and not always how to do.
Besides sharing some of my experiences, I want to touch on the three pillars of teaching.
- Collaborative Learning
Who is the talk for?
Have you ever had to show a junior developer something? Maybe you had to explain a design pattern to someone that had no idea design patterns for software development existed. After your initial shock of realizing that a developer doesn't about the GoF, you attempted to explain some of the concepts. Maybe it went fairly well, maybe you were frustrated beyond belief. Either way, this talk is for you. With any luck, after the talk, you will be able to understand a little more what it must be like looking into the giant world or programming, and be able to teach a little better.
There are a lot of workshops and courses from everything like web developer bootcamps to just learning Rails or some other framework. These workshops are a ton of work. If you have ever taught one of them you know the plan gets tossed out by the second lesson.
After this talk, you will have the knowledge necessary to adjust quickly while keeping your main objectives in place.
Even if you know all about how to teach in a technical setting, my hope is that you can pick up one thing. Or at least bring up good points for discussion.
We are all educators
The last point I want to make is this. We are all educators. Every last one of us. The face of education is changing. The Internet allows any person to find an enormous amount of information. Given that information is available, College isn't always the right answer. Some people just want to know how to build a website, or how to make a poster, or how content marketing works. If you know one of these things, you are the teacher. You can educate your peers. And you will learn more than you ever thought you would.
I invite you to teach your peers and help shift education as you know it.
Posted on: Sunday April 06, 2014
Today I learned that you can sign documents with Preview and your webcam on a Mac. This is perfect.
Posted on: Monday March 24, 2014
I'm tired of Kickstarter. It seems we, as a people, have lost the art of building something and selling it. Everything is a Kickstarter campaign.
Now, when I see some product is a Kickstarter project, I immediate lose interest and close the tab.
Show me something I can purchase.
Show me something that you created. Not an idea that may or may not turn out like I expect.
Posted on: Saturday March 22, 2014
I have a confession to make. I actually like all the business stuff required while running a software company. I used to hate setting up meetings, chasing down leads, and all the other stuff that I have to do to make a living building software for other people. This time around it's different.
I guess I just started learning how to do it properly. It makes a huge difference in how I approach it when I know what to expect.
Here are a few of the things that I think make it more enjoyable.
Listen - When I started opening my mind to really listening to people and trying to help them with no strings attached, the conversation quality really jumped. I stopped worrying about if I was going to get paid and concentrated on developing friendships.
Patience - Sales never close on one encounter. It could take 3 or 4 or 10. It depends. I stopped worrying about it, and started looking for ways I could help with their problems.
Be Picky - I learned I don't have to do business with everyone. Some people are a really bad fit for me and that's okay. They are looking for the cheapest labor they can find. Yes, some people see software developers as labor. Just a robot punching a keyboard. These are not the type of people I am drawn to, and when I stopped talking to them I enjoyed the art of business more.
I'm still learning, but it's more fun this time around.
Maybe failure is required the first time?