Finding complexity when writing technical documents


I was recently writing the landing page text for Artemis, the calm feed reader I am developing. In the first three sentences on the page, I wanted to communicate what Artemis is, for what you can use the reader, and the fact that the reader only updates once per day.

Here is what I came up with:

Artemis is a calm web reader.

You can use Artemis to follow your favorite websites.

Artemis updates once per day, at approximately 12am (UTC by default, but you can change this in your settings).

In the first and second sentences, I clearly communicate what Artemis is and that you can use the tool to follow websites. The third sentences, however, left something to be desired. I had to use parentheses.

When I wrote the sentence that describes the reader update cadence – a distinguishing feature of the reader – I communicated the status quo. On registration, the time zone would be set to UTC. This means that a user’s reader would update at around midnight UTC. With that said, there was an option on the settings to change your timezone.

I started to think: why should the user even need to change the value in their settings? Why can’t it be inferred on sign up? Better yet: why can’t I infer the user’s timezone according to their device timezone, and make it part of the sign up process so the user can still choose their own timezone? I felt like I was trying to communicate technical details that were not necessary if the app did more in the background. This was counter to my goal of communicating in as simple language as possible the what, why, and how behind the software.

After writing the third sentence, I went back to reflect on the sign up experience and made a few changes to reduce the complexity that I had identified. I:

  1. Added a new timezone field on sign up, which a user must submit to sign up.
  2. Wrote some JavaScript that would pre-fill the timezone field with the user’s current timezone.

I then revisited my introductory sentences, changing them to:

Artemis is a calm web reader.

You can use Artemis to follow your favorite websites.

Artemis updates once per day, at approximately 12am in your timezone.

That’s better. I no longer need a parenthetical. I don’t need to mention UTC. And I can better communicate that the software works in the user’s timezone. This both adds important information to understand what it means to update once per day, and subtly emphasises a design principle that I kept in mind when the software: that the reader should work according to the user’s preferences.



Source link

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top