Skip to content

Choosing an article topic

A good tutorial teaches the reader something that is useful. A good source of inspiration is things that you have battled with recently (so you can still remember what was hard about it) -- either because you had to visit many different sources to figure out how to do something, or because none existed and you had to figure it out yourself by reading source code or reference documentation.

A good topic is:

  • Self contained: something that you can code in around 10-20 hours and that the reader can then copy in 1-4 hours.
  • Not already available: your topic shouldn't be a direct copy of something that's already available, or something too trivial (e.g. "Build a basic frontend with React").
  • Interesting: not a variation of a topic that has been done many times before (see some example below).

A good pattern is "how to build X with Y and Z", combining two frameworks, langauges, platforms or similar. To do this without a tutorial, a reader would often have to comb through the documentation of two different sites. You can make it easier by having everything in one place.

Cliched topics that we avoid

There are some projects that are used so often in tutorials and example projects that they have become cliched. We avoid these (this is a non-exhaustive list).

Micro blog site or Twitter clone

  • A twitter clone or other simple microblogging site where people can post messages

To do list or Trello clone

  • A todo list or Kanban board

Temperature / other conversion tools

  • a way to convert celsius to fahrenheit or similar conversions (inches to cm, etc)

Making 'evergreen' articles

Nothing lasts forever, but we should attempt to ensure that our projects are long-lived. Therefore those based around time-specific events (e.g. COVID-19, a specific sports match, etc) should be avoided

Using free software

Ideally, we only demo free and open source software. We should avoid things like the Twitter API, the Google Maps widget, and Firebase as these are known for changing (both in functionality and pricing) and breaking example projects.

We should also avoid relying on software or APIs that have not been around for at least 5 years.

These are guidelines - in some cases, it is necessary or preferable to use proprietary software or APIs. In these cases, we should ensure that our demo works on a free tier or similar.