Tech Content Creators' Responsibilities

Why Shouldn't We Shout Everything Into the Void?

As online learning flourishes, it’s easier than ever to learn new things. If we search for virtually any technology, we’ll get remarkable amounts of results. In some sense, it’s good, since we have the freedom to choose. But how should we make that choice?

Judging Content Quality

There are multiple properties of a tech course - let it be text- or video-based. Usually, it’s easy to instantly get an impression of content quality by looking for clues:

  • Grammar, accent
  • Illustrations
  • Text understandability
  • Visual design
  • Examples
  • Clarity of the explanations

And the list could go on.

We have biases against content based on the above impression. And sometimes these biases are harmful:

  1. We could quickly close a very good article because it’s hard to read due to an unfortunate font or color choice
  2. We may get fooled by content, that checks all the above boxes but has other, harder-to-detect problems

Point one is only harmful to the content’s publisher: fewer people will use what they created.

On the other hand, point two is bad for consumers. The reason is simple: if the creator puts in the effort to produce high-quality content from most perspectives, we tend to think it’s indeed high-quality from every aspect. Unfortunately, in many cases, we’re wrong - and the author doesn’t necessarily do this willingly.

But what are these hard-to-detect problems?

The Hidden Quality

Let’s consider a simple example: we’re looking at a tutorial about the most recent JS framework: RockIT.js (patent pending)1. The examples are simple, to let the reader concentrate on core concepts without technology and domain getting in the way:

<html>
  <body>
    <div id="content"></div>
    <script>
      RockIT.bootstrap('#content', '<h1>Hello World!</h1>');
    </script>
  </body>
</html>

Another, featuring click events:

<html>
  <body>
    <div id="content"></div>
    <script>
      function click() {
        window.alert('Hello World!');
      }

      RockIT.bootstrap('#content', '<button @click>Click me!</button>');
    </script>
  </body>
</html>

Here it’s easy to see a problem: JS embedded in HTML and HTML embedded in JS. For quite some time we know that these are bad ideas.

But beginners don’t have the experience to recognize the problem. The approach looks simple enough, so they get the evergreen CPDD2 from their toolbox and start writing code garbage. Because the examples above aren’t more than garbage in large-scale applications.

Whose fault is it? In my opinion, it’s the creator’s responsibility to present best practices. And in the above examples, they failed miserably.

Best Practices

As technology evolves, best practices come and go. What people considered best practices a few years ago, might be antipatterns today. But that doesn’t mean we shouldn’t strive for using current best practices.

What happens if we don’t? Let’s get back to the examples above. Our beginner reader uses the framework with satisfaction. They’re sharing their experience with friends, even starting a blog3. The blog’s readers start sharing, too. The bad habit is spreading. It’s a downward spiral.

But it isn’t only spreading. As people keep using the practice, it’s solidifying until it becomes a habit.

Later, they see an example, where all the files are separated:

<!-- index.html -->
<html>
  <body>
    <div id="content"></div>
  </body>
</html>
// hello.js
RockIT.bootstrap('#content', 'hello.html');
<!-- hello.html -->
<h1>Hello World!</h1>

Most probably they’ll think that this example is strange and overcomplicated. It has three files instead of one. They can’t immediately oversee the implementation. (Funnily, as the application grows, the one-file solution will be less understandable. But they might not see that yet.) And most importantly: they’re used to a different style. And it’s much harder to change an existing habit than to form a new one.

Most probably, the content creator didn’t mean all this to happen. Maybe they weren’t aware of the best practices. Or they didn’t know the impact it might have on the community. But despite their intentions, the harm was already done and it’s extremely hard to revert.

Let’s see a real-life example. The average developer codes for quite some time before they write their first unit test. They’re used to manual tests clicking every button until the application seems working. It’s strange for them to write tests. And we didn’t even talk about using TDD.

On the other hand, what happens if we train someone from day one to use TDD? Developing with TDD will be their habit and it’ll be strange to do things differently.

And that’s exactly my point. To successfully spread best practices, we must start early. Especially those with a higher abstraction level. Let that practice be technological, methodological, or architectural. Bad practices are similar to fires: we should prevent them instead of putting them out.

Conclusion

As consumers, we should be critical. We shouldn’t copy-paste blindly code examples. We should try to understand the concepts, and apply best practices whenever we can.

As content creators, we must not cut corners. We should have a deep understanding of technology, the most recent industry standards, and architectural styles. We should build those into our materials. At the end of the day, we’re not responsible for how others use the technology we’re presenting. But at least, we did what we could.


  1. I hope it’s obvious that I’m just fooling around with this non-existing framework ↩︎

  2. Copy-Paste Driven Development ↩︎

  3. It seems that these days, anyone can do that ↩︎


See also