2018-06-28: Writing docs? Choose your examples carefully

Software documentation is built around examples.

Inevitably, these examples use business as the example domain. In database docs, customer and product tables abound.

This is a missed opportunity. Good documentation should not only show how the software typically gets used, but should convey possibility: what could the software be used for? What great things should be built with it?

Choosing boring business-focussed examples throws away these possibilities.

Capitalism has pushed the ideology of business and managerialism into every dimension of life, including software, a world dominated by billionaire-owned corporate tech giants.

This is especially obvious when you see application-specific logic referred to as "business logic", even though the software in question isn't specific to the needs of "business".

But software can be so much more than a profit-generating technique for big tech corps. Software can be publicly owned, and run tools and services for the public good.

Software for selling ads and optimising up-sell is boring. After starting my career in the private sector and hating it, I decided to avoid it as much as I could.

Since then I've worked on scientific supercomputing, making government services run better and fairer, and built software to help the union movement rebuild the working class. These problems are much more interesting.

Writing docs for a geospatial database? Use global temperature tracking or public transport access analysis as an example.

Writing docs for a data science tool? Use an example that loads the Panama Papers data and explores it.

Writing docs for an inventory app? Why not use a public library as your example?

Resist the neverending creep of "business" into every facet of our lives. Use examples that inspire a world outside of it and even beyond it.