Creating Example Projects

Show me the code. That phrase will inevitably come up when people talk about software. Software, by it’s nature, is abstract. When you’re having a long discussion about software, it’s easy to get away from the main point. Until you’re looking at the same piece of code, it’s easy to let your imagination run wild, and talk past each other. The code you create matters. Code is the clearest way to demonstrate your ideas  — much like talking about a book that hasn’t been written yet, and somebody requests a chapter of that book. The content, structure, and style are meaningful.

If you were to write a book about software, or create a video tutorial series, you need to create code for it. It’s a common practice to create an application for your examples. There are two mutually exclusive approaches you can take to build that application – a brown field application, and a green field application. A brown field project is an existing application, usually referred to as legacy after a subjective period of time. A green field project is a new project, with no existing infrastructure – a fresh start.  Which is right for your project? That is the question.

The Brown Field Application

Lets start with the brown field application. Before you can really start creating the content for your book or video series, you need to create a working application, that demonstrates outdated and poor development practices. That is gonna take a while. During the development of this application, you need to keep in mind your content, and the principles that you want to teach. That way those principles can be demonstrated in your code. Developing this application is going to be challenging. If you make it too big, your book will be too long, or your videos will be to numerous. However, if you make it too short, or make it too simple, then you won’t have enough content to convey, or develop enough lessons. So, before you even start developing your content, you’re at a disadvantage. You need to satisfy this tricky balance.

Another downside to creating a legacy application, is that there are a lot of bad practices out there. If you don’t mention one of them, can the learner conclude that a particular practice is ok? In short, there are 100 different ways you could show somebody how to fail. However, there are far fewer ways to show somebody do things right.

It’s not all downsides though. From a learner point of view,  it can be quite helpful. Developers usually have to manage a legacy application. So if you can meet them where they’re at, it can feel more practical. You can demonstrate how to improve the reality they’re in. A significant part of improving a legacy application is teaching them how to pay down technical debt. You’ll be teaching them how to improve their code base, as they progress through your content.

The Green Field Application

The green field application is a very different approach – one that isn’t laden with a history of compromise, technical debt, and regret. You get a fresh start, and can begin on the right foot. In contrast to the brown field approach, you don’t need to develop your application beforehand. You can develop the application during the process of creating your content. Part of the reason for writing a book, or creating a video tutorial series, about software, is to use your experience to help people avoid your mistakes.

When you develop an application, there are many decisions to be made. During the content creation process, you can use these decision points to explain any relevant best practices. You could also explain the downside of doing things the legacy way, in order to explain how the best practice came to be. Brandon Savage wrote The ‘best practices’ that have been written about, agreed upon and talked about don’t exist out of thin air, but are hard-won knowledge derived from experience.

When learning something new, it’s useful to strictly interpret every rule you learn. It provides a framework for you to work within. This allows you to be effective, while you’re still learning. Eventually, you’ll encounter a scenario when you need to loosen your interpretation of a rule. You expand your mental model about a subject, as you begin to understand that context is important to acknowledge when applying rules. As you learn about other topics, you learn that where and how things happen also has a significant impact. Trade-offs have significance and weight to them. The more experienced you become, the faster you make this realization when discussing new projects, to the point when your default response becomes – it depends – which is usually aggravating to the other party. While you may say this nonchalantly, the other person gets the sense you’re acting like the  “there is no spoon” Buddhist kid in the Matrix. The fastest way to get someone to where you are, is by teaching them best practices from the start.

Another advantage to choosing the green field route, is that you’ll need to write less code. You can just focus on building your application right the first time. The less code you write, the less code you’ll need to maintain in the future. Every good developer I know takes great pleasure in removing unnecessary code from their code base. It provides clarity to the remaining code.

Conclusion

What is the right path for you? Only you can decide for yourself. However, in the majority of cases, I’d recommend the greenfield approach when you’re teaching people. You won’t have to teach them to un-learn. Instead, you can just start them off on the right foot.