What I think about when I edit

I’m often asked to edit friends’ or coworkers’ writing, anything from emails to short stories to documentation. Recently, someone asked me how I edit. What am I looking for? How do I know what changes to make? That made me stop and think about what I’ve been doing semi-instinctually.

In this post, I want to distill the major points of editing that I believe in but haven’t spelled out until now. Much of this advice applies across genres. Personally, I wrote academic papers in college, write poetry and short fiction in my free time, and write technical documentation for work, and I’ve applied the same basic editing techniques to all.

I also think that different genres inform each other. There are principles I’ve taken from fiction writing that make my technical language even clearer, and learning just how much people skim when reading technical documentation has improved how I format and write things like emails.

Here are my recommendations:

• Decide what you’re actually saying
• Repeat yourself (within reason)
• Simplify
• Eliminate passive voice
• Don’t use adverbs
• Don’t assume knowledge
• Be aware of your tone
• Avoid jargon and cliches
• Make use of whitespace

---

Decide what you’re actually saying

Before you ever get to editing at the sentence level, you have to determine whether you’ve said what you meant to say.

I recommend writing a preamble*, just for your own use, on everything you write. Take a few minutes and consider what you’re trying to say. What is your main point? Who are you writing for? Then actually write this information down at the top of your document (or notebook, or cafe napkin) so it’s there staring you in the face as you work. As you write, and as you edit, you can compare what you have on the page to what you set out to do.

It also forces you to think about what your message actually is. Say you want to write a blog post: if you can’t summarize the point you want to make in a sentence or two, how are you going to write a coherent post?

*I took this name from something we do in my creative writing classes at the Writers Studio in New York. As part of every assignment, we have to write a preamble: a few sentences at the top of the page mentioning what we intended to do, including the kind of narrator, tone, and mood. When other students critique your work in class, they’re holding it up to this model and evaluating whether you achieved your aim, focusing on craft, not whether they like your main character.

Repeat yourself (within reason)

Even if you think you’ve made your point very clearly, it’s worth restating it at the beginning and end of what you’re writing to make sure the reader gets it.

This principle applies across most genres. In documentation, a good tutorial will have a brief introduction to what you’re going to do, then the actual procedure, and finally a way for you to verify that you’ve done the thing correctly. In a blog post, you should introduce what you’re going to discuss in the post, then actually do that, and have a short summary at the end. And so on.

“Repeat yourself” applies at the language level too. One of the best writing tips I've ever gotten was to avoid using demonstrative pronouns. Instead of saying “this” or “that,” you should add a noun to spell out exactly what you’re referring to, even if you’ve just mentioned it.

Example: We only have two boxes left. To solve this, we should order more.

Revision: We only have two boxes left. To solve this shortage, we should order more.

Example: Click next and enter your credentials when prompted. That will take you to the home screen.

Revision: Click next and enter your credentials when prompted. Successfully authenticating will take you to the home screen.

This duplication can feel repetitive when you’re writing it, but it won’t feel repetitive to your reader—it’ll make your writing clearer and easier to follow.

In summary: when editing, look for ways that you can restate your point, clarify, or provide closure for the reader.

Simplify

When I edit someone else’s work, my number one quest is to remove words. Eliminate the fluff. Are there constructions that can be shortened? Any extraneous words that don’t add to the meaning of the sentence?

Example: You will need to run this script.

Revision: Run this script.

Example: You can aid in readability by making sure that the names of things properly communicate what they do.

Revision: Make sure the names of things communicate what they do.

Unless you have a very specific reason not to, strive to get to the point as quickly as possible. Don’t bury your meaning in excess words and flowery constructions.

Other ways to simplify:

“You should”/“You can”

When writing instructions, anywhere you say “You should X” or “You can X,” replace it with the imperative mood of the verb.

Example: You should save the file to your home directory.

Revision: Save the file to your home directory.

This change eliminates a couple words, making the sentence easier to read, and brings the reader straight to the point.

“Of” and “for” clauses

Instead of using constructions with “of” or “for,” rewrite the sentence to put more information before the noun. This ordering makes the sentence more efficient.

Example: The manager of the team responsible for marketing

Revision: The marketing team’s manager

In the rearranged version above, the reader can more quickly grasp what you mean, instead of having to revise her understanding after each clause.

Split it up

Break up long sentences into multiple shorter sentences.

Example: Due to the Acme project which just completed a major milestone of having all non-staging servers running in the Foobaz environment, we now see build times of sub-10 minutes which were previously taking over an hour when running with the XYZ plan.

Revision: The Acme project recently completed a major milestone: all non-staging servers are now running in the Foobaz environment. Builds now take fewer than 10 minutes to complete. This change is a significant improvement, as builds on the XYZ plan previously took over an hour to complete.

Also, break up sentences by adding commas where appropriate. For example, I’ve noticed a trend towards people dropping commas after subordinate clauses. I always add them back when I edit:

Example: If you’re looking for me I’ll be in my office.

Revision: If you’re looking for me, I’ll be in my office.

Example: Due to the fog our flight was delayed.

Revision: Due to the fog, our flight was delayed.

I suspect that this is because, when we speak colloquially, we don’t pause at that point in the sentence. However, grammatically, you need a comma after a subordinate (or dependent) clause when it comes at the start of a sentence. Besides being “correct,” the comma helps the reader pause and process what they’ve just read before moving on to the rest of the sentence. Using commas after subordinate clauses improves reader comprehension.

Eliminate passive voice

You’ve heard this advice before. But you should understand why you shouldn’t use passive voice in your writing. It’s not just “bad style.”

Passive voice obscures who or what is performing the action. Rewriting a passive construction to be active almost always makes what you’re saying clearer and makes the sentence easier to read, because your reader can attribute the action to the right person or thing.

Example: The fire alarm was pulled and the building was evacuated.

Revision: The fire marshal pulled the alarm and the employees evacuated the building.

Example: Millions of dollars were embezzled from the company.

Revision: Two executives embezzled millions of dollars from the company.

It may even help you understand what you’re saying better. If you’re describing a system you built, and you say “An alert is triggered and the job is started”—do you know how those things happen? Which service triggers the alert? Which component is responsible for executing the job? In rewriting, you may realize that something doesn’t work as you expected, or that you don’t know how it works.

In technical documentation, you lose precision when you don’t attribute the action to someone or something. And in all writing, refining your language refines your understanding of the world.

Don’t use adverbs

This aversion to adverbs is one of the principles I’ve taken from fiction-writing.

You can almost always replace an adverb with a better, more specific verb, or describe what you mean instead. Being more specific is especially key in fiction, but I believe in stripping out adverbs in all types of writing.

There is nothing inherently wrong with adverbs. They are just part of a category of things that I believe are lazy in writing. When I say “He laughed loudly,” I’m relying on my reader somehow intuiting the precise volume of his laughter. “Loudly” could mean a million things, but what I really had in mind is that “He laughed with the kind of booming abandon that made the whole restaurant turn around and look.”

People also often use adverbs as a hedge: “Basically, it's this.” “Essentially, this is what I’m saying.” Is it, or isn’t it? Remove the adverb and commit to saying whatever you’re saying.

Don’t assume knowledge

It’s easy to fall into this trap when you’re writing about something you know well: you forget to consider what you know that your audience doesn’t. You don’t take a step back and provide relevant context. Imagine how much more pleasant it would be to read emails, documentation, etc., if people actually spelled out those TLAs (three-letter acronyms)!

Let’s start with an example, and look at a few ways we can improve it.

Example: This chart shows the TTFB for our website over the past week.

To some people, this sentence makes perfect sense. To many people… not so much.

• Spell out acronyms on first use. Any time you introduce an acronym or an initialism in a document, spell out what it means and put the acronym in parentheses. Thereafter, you can use the acronym by itself.

  Revision 1: This chart shows the time to first byte (TTFB) metric for our website over the past week.

  You might think it’s obvious what an acronym means, but a new reader may not.

• Add a phrase or a sentence briefly explaining a concept when you introduce it.

  Revision 2: This chart shows the time to first byte (TTFB) metric for our website over the past week. TTFB measures how long it takes from when a user makes an HTTP request to when the user’s browser loads the first byte of data. It’s used as an indicator of how responsive a website is.

• Link out to further reading. Once you define a concept and the corresponding acronym, provide a link to somewhere that the reader can learn more about that concept if they’re still curious. You don’t have to call attention to the link.

  Revision 3: This chart shows the time to first byte (TTFB) metric for our website over the past week. TTFB measures how long it takes from when a user makes an HTTP request to when the user’s browser loads the first byte of data. It’s used as an indicator of how responsive a website is.

By now, your readers are with you, and they’re ready to proceed, feeling confident that they have an idea of what you’re talking about.

Be aware of your tone

Know what kind of tone you’re going for, and be consistent. You can be colloquial or formal, but not both.

Example: We were really into this new framework that we found for like a minute or two, but the metrics captured by the system do not correspond precisely enough to our investigative goals to be useful.

Revision: We were initially enthusiastic about the X framework, but we found that it did not capture the metrics we were looking for.

The original sentence starts out very colloquial and then morphs into formal, almost academic language. In the best case, you’ll confuse your readers about why you switched. In the worst case, you’ll completely distract them from what you’re saying.

Avoid jargon and cliches

In the business world, jargon means things like “deep dive“ and “low-hanging fruit”. Elsewhere, we love to use cliches. Especially baseball metaphors, for some reason: “step up to the plate,” “hit it out of the park,” “take a swing at it.”

It will always be better and clearer when you say exactly what you mean. Using jargon is lazy, and it assumes that the reader is part of the in-group that uses that jargon (see also: Don’t assume knowledge, above). It can be difficult for non-native English speakers (or non-Americans, when it comes to baseball) to follow your writing when you use jargon and cliches.

Example: tl;dr, if you can hack something together by EOD, that would be great.

Revision: Can you deliver a prototype by the end of today?

The original sentence has incomprehensible acronyms and tech slang, and doesn’t even sound like a request. The second one is straightforward, and asks for what the writer needs and by when.

Make use of whitespace

Whitespace is key for technical documentation but can also be used to great effect in blog posts, emails, and elsewhere. It’s hard for people to read long paragraphs, especially on a computer screen. They will zone out. Ensure that readers stay with you by visually breaking up the page and making your key points easy to identify.

A few suggestions:

• Break up long paragraphs into multiple shorter ones.
• Use useful subheadings to give your document some structure and allow readers to skip ahead to the section they’re interested in.
• Use lists where relevant, because it’s easier to read a bulleted list of items than to read a paragraph with the same information.
  • When you need to convey large amounts of information (for example, in reference documentation), tables are even better than lists.
• Use bold so that readers who skim (i.e., everyone) will still pick out your main points. (For an example, see the body of this post.)

---

Conclusion

To simplify what you’ve just read, my editing philosophy can be reduced to two tenets:

• Say exactly what you mean, which means not relying on adverbs, jargon, cliches, or hedges, and
• Take out all unnecessary words.

Keeping these two tenets in mind will help you in your own writing, and will give you a framework for evaluating other people’s writing. Over time, as you practice, you’ll develop your own style and preferences. You may end up diverging from some of my recommendations, and that’s great, as long as you know why you’re doing so. The point of editing is to think about how you’re using language and to make choices that suit the message you want to deliver, not to unquestioningly follow rules—mine or anyone else’s.

In which I vent more about Antora

Part 3 of my Hack Week recap

For the sake of giving my original post a consistent structure, and not boring the non-tech-writers who might want to read it with exhaustive detail, I left out additional observations from my experience using Antora.

Writing experience

My next complaint: Antora doesn’t offer a way to set up a watcher or otherwise live-reload changes to the docs as you make them. Additionally, because you're making content changes in a different repo than the one where your site lives, the process for previewing a docs change looks like this:

1. Make a change in <content-repo> and save your file.

2. Commit and push your change.

3. Remove the cache directory in <configuration-repo>.

4. Run the equivalent of a git pull in <configuration-repo>.

5. Rebuild your site.

If you're someone like me, not being able to preview changes easily as you make them slows your writing down and makes you feel like you're going about it blindly. If you're a developer, it likely means you will not preview your changes locally at all.

Features that did not live up to my expectations

The difficult of setting up an Antora project and writing docs in AsciiDoc would be enough by themselves to rule out Antora as a tool for internal docs, but as a bonus, here are a handful of Antora features I was excited about that disappointed me.

Partials

Antora has the concept of partials — the ability to pull text from File A and include it within File B — which is a feature in Sphinx that I miss in our Markdown-based current system. However, one of the best uses of partials is to include excerpts from code files, which Antora doesn't support.

For example, say you want to document your product's configuration.yaml file. Rather than copying the default version of that file into the docs, you can include it directly from the source. Then you don't have to worry about the docs version getting out of date, since it's always pulling from the latest code.

RST:

Configuring the product
=======================

The default `configuration.json` file looks like this after installation:

.. include:: <path>/<to>/configuration.json

Description of properties
-------------------------

* `title`: Set this to your desired title...

Again, this is not currently possible in Antora, though the documentation notes that this will be possible in future releases:

Currently, all of the example files you want to include must live in the examples directory inside the current module. In the future, it will be possible to pull in example source code and files from other locations.

So while having partials is better than nothing, this feature in Antora is currently of limited use.

Navigation files

Navigation files let you define which pages to include and in what order. This is a feature I appreciate, but a) the syntax is fussy and b) you have to provide the title yourself! In Sphinx, you simply specify the filename, and it pulls the title from the file's H1 heading.

Antora:

* xref:overview.adoc[Overview of the Product]
* xref:troubleshooting.adoc[Troubleshooting Your Local Environment]
* xref:tutorials/advanced.adoc[Advanced Tutorial]

RST:

.. toctree::

   overview
   troubleshooting
   tutorials/advanced

Listing files from different components and modules adds more to the Antora syntax, and I didn't even touch different versions.

Pulling content from multiple repositories

At last, the feature I was most excited about: bringing together content from multiple repositories.

I longed for this feature at my last job, when a single product had code spread across multiple repositories and therefore released multiple sets of release notes. I wanted to pull all of these release notes files into the same docs site and was forced to cobble together a build command that checked out each of the repositories, built each docs project separately, and then copied the built files into the right locations. Antora, I thought, could have solved this.

To test this, I simply wanted to include a couple pages from a second repo in my table of contents. I added this to my default navigation file:

.Content from Repo 1
* xref:introduction.adoc[Overview]
* xref:othertopic.adoc[Some topic]

.Content from Eva Test
* xref:evatest:ROOT:guide1.adoc[Guide to topic 1]
* xref:evatest:ROOT:guide2.adoc[Guide to topic 2]

It built fine — but every time I clicked on one of the "evatest" pages in the sidebar, it took me out of the default navigation and loaded a totally different sidebar with a different table of contents. What I really wanted was for all of the pages I specified to be part of a single project, and I never accomplished this.

Why Sphinx and RST are the best

Part 2 of my Hack Week recap

For comparison to the two newer tools (Antora and Docusaurus), I also ported my docs to Sphinx.

Full disclosure: I spent more than three years using Sphinx full-time at my last job. So while I am aware of some of the idiosyncrasies and difficulties of the tool, I'm used to them and know how to solve them.

Still, I ran through the whole installation process and used the quickstart generator to create a new project, and I was able to get a working site up within a few hours. This included the time it took to convert my Markdown docs to RST via Pandoc and then fix all the links.

Since I wasn’t exactly evaluating Sphinx as a brand-new user other than during the setup process, my experience was mostly a beautiful reunion between me and my favorite features of the Sphinx/RST tool set. This post will discuss several of these and other reasons why Sphinx remains the best tool for technical documentation.

RST features

Sphinx uses reStructuredText (RST) as its markup language. While it is different from Markdown, it is not as excessive as AsciiDoc.

The issue I've run into with RST is that people (*ahem* developers) are mystifyingly resistant to it. I've heard lots of complaints along the lines of "It's so much harder than Markdown." Again, I may not be the most representative user, but I do not find it much harder than Markdown. Furthermore, the documentation-specific features it adds are well worth it.

List tables

For this feature alone I would choose RST over Markdown any day.

Compare these two options for creating a table.

Markdown:

| Treat         | Quantity | Description                                                     |
|---------------|----------|-----------------------------------------------------------------|
| Albatross     | 2.99     | On a stick!                                                     |
| Crunchy Frog  | 1.49     | If we took the bones out, it wouldn’t be crunchy, now would it? |
| Gannet Ripple | 1.99     | On a stick!                                                     |

RST:

.. list-table::
   :header-rows: 1
   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
     crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

Imagine having to edit the first table? What if you added a cell that was longer than one of the existing ones, and had to realign all that ASCII art?

(Confession: I used an online Markdown tables generator to make the Markdown version. That's how much I didn't want to write it out myself.)

Toctrees

I've mentioned toctrees before, but they're honestly worth the price of admission for using RST and Sphinx.

Include a toctree in any file, list the filenames you want included, and just like that, Sphinx will build you a page hierarchy.

index.rst:

.. toctree::
   
   install
   getting-started
   release-notes/index

release-notes/index.rst:

.. toctree::

   v2.0
   v1.1
   v1.0

This creates the following hierarchy:

index
├── install
├── getting-started
├── release notes
         ├── v2.0
         ├── v1.1
         ├── v1.0

Dynamic linking with :ref: anchors (aka cross-references)

Specify an arbitrary text tag (ref), and then link directly to that tag. This works within files, across files, even across Sphinx projects with the intersphinx extension. You can rename or move files, and your link won't break. If you use a ref before a header, you don't even need to supply link text — it'll pull the header text automatically. (You may know this feature as "cross-references" if you're familiar with XML-based tools like Madcap Flare. But with Sphinx you don’t have to pay $1000 per seat for the privilege!)

Include external files

As mentioned under Antora, RST lets you specify the path to a file and pulls in content from that file. You can even specify line numbers to include only part of the external file, or specify tags if you've marked up the external file with the area to include. I've seen this used to great effect with code samples.

Variables

You can use the rst_epilog feature combined with substitution definition to define variables that should be available in every RST file. For example, you might use a variable for your support team's email address (if the email changes, you can update it in one place rather than all over your docs), the product name (I've been on many projects that rename their product once or twice during the development process), the end date for your copyright range, etc.

Additional code block features

In additional to language-specific syntax highlighting, Sphinx also gives you the option to highlight certain lines in a code block with the emphasize-lines parameter. In a tutorial, this lets you show code in context but still draw attention to the lines that the reader needs to add or modify. You can also provide a caption for the code block (for example, to display the name of the file the code should go in).

Theming

Swapping themes in and out of my Sphinx project was painless, and there are tons of options out there. You simply install a theme locally, then import it and invoke it in your conf.py file.

I also discovered that many of the features I admired in other documentation generators are possible in Sphinx with a different theme. For example, I like that Docusaurus's "next/previous" navigation buttons list the title of the next and previous page. Lo and behold, the Guzzle Sphinx theme does this as well.

Extensibility and wide use

As a more established tool, Sphinx has many, many extensions, themes, and cheatsheets available. The creators of Antora and Docusaurus seem active in supporting users on Github and Gitter/Discord, but for getting help, Sphinx still wins due to the vast amount of information (and StackOverflow answers) out there.

Conclusion

The combination of Sphinx+RST remains, for me, the most powerful documentation tool. If it were just up to personal preference, I’d choose it for our docs in a heartbeat. However, developer adoption is a major factor, and we may need to stick with Markdown to ensure that everyone is willing to contribute to the docs. (Then again, they might surprise me!)

An additional consideration is what language the tool is written in — the tech writing team can do some maintenance ourselves, but we largely rely on developers to set up the infrastructure for whatever documentation system we choose. So if our colleagues are more comfortable with Python or React, Sphinx or Docusaurus is going to be an easier sell.

There are still other tools we want to evaluate, so our search for the ideal docs solution isn’t over. But this experiment gave us more information on the kinds of issues we might experience when converting all our docs, and a better sense for how we value features versus complexity.

Antora and Docusaurus duke it out

Introduction

For Squarespace's most recent Hack Week, I tried out three different documentation tools, with an eye to replacing our current internal documentation system.

Since Squarespace's internal engineering documentation team was established a year ago, we've made progress towards standardizing on a documentation system and establishing best practices. As a small team of writers, a major part of our job is making it easy for developers to write and publish their own docs. We've migrated most teams to writing in Markdown and storing the source in Git repositories.

But one piece of the puzzle is still in progress: a static site generator to turn those source files into self-contained, attractive HTML sites.

For Hack Week, I chose to evaluate two of the newer options on the scene (Antora and Docusaurus), as well as one of the most established (Sphinx). This post will compare Antora and Docusaurus. Stay tuned for a follow-up post about Sphinx.

Antora

Antora, by OpenDevise, is very new. It released its first alpha in January 2018, and released 1.0.0 in April.

I will admit upfront: I wanted to love Antora. It purports to be "The Static Site Generator for Tech Writers," and How Antora Can Help did promise lots of features I wanted.

However, it took me two and a half days to get a functioning project, and I'm still not convinced I did it right. Additionally, the killer feature I wanted (the ability to pull content from multiple different repositories) didn't pan out.

Getting started

I’ll walk through my experience trying to get a working Antora site, but if all the terminology makes your eyes glaze over, just skip it — the takeaway is that the process is as confusing to go through as it is to read about it.

First, you should know that Antora has you divide functionality into three repositories:

• a repository with the actual content, which must adhere to a specific directory structure and contain an antora.yml file with metadata about that content

• a repository for your "playbook," which defines where to pull content from, which UI to apply, and where to publish your site (essentially, configuration)

• a repository that defines the UI for your docs site (essentially, theme)

Antora doesn’t provide a quickstart generator, but they do have a demo playbook repository that you can download. After wading through the lengthy system requirements and installation docs, I downloaded the demo repo. I decided to ignore the part about putting content and configuration in two different repos, and used the demo repo for both my playbook and content.

The issues I ran into were partly conceptual and partly technical.

Conceptually, I struggled to understand how I should define a component versus a module. An antora.yml file denotes a component and has metadata like title and version, plus a reference to a default navigation file. But the navigation file itself is nested within a particular module. I never got as far as determining whether and how you could combine nav files for a complete table of contents.

I eventually decided that a component is intended to correspond with a repository, and then modules are essentially just subdirectories with a stricter structure.

For example, if you had organized your docs repository into getting-started, installation, etc., each of those directories would become a module (each of which has subdirectories for pages, assets, etc.):

docs/
|- antora.yml
|- modules/
   |- ROOT/
      |- assets/
      |- examples/
      |- pages/
      |- nav.adoc
   |- getting-started/
      |- assets/
      |- examples/
      |- pages/
      |- nav.adoc
   |- installation/
      |- …

On the technical side, once I’d put my content into a module, I spent a long time trying to get my docs to build.

Antora really wants you to use multiple Git repositories. Because I had put everything (both configuration and content) in a single repo, I had to figure out how to build from local source files instead of from a remote repository. I read the content sources documentation thoroughly, and tried different combinations of paths, branches, and the start_path option, before I came across this issue with a relevant example for what I wanted.

My verdict? Antora’s initial configuration is too difficult.

I understand that Antora's level of specificity is by design, and as a tech writer I appreciate standardization. For example, I've often been annoyed when some people put image files in images, some in _static, some in /images. But Antora asks a lot of overhead knowledge from contributors, and I worry that will scare away developers from contributing, let alone starting a new docs project. We need a docs solution that lets teams be as self-sufficient as possible.

AsciiDoc

Antora has you write documentation in AsciiDoc. Since all of the documentation I’ve written at Squarespace is in Markdown, I had to rewrite it in AsciiDoc.

Here we encounter the next thing preventing me from liking Antora: oh my god I hate AsciiDoc syntax so much. Yes, I know that this is not the fault of Antora itself — but its creators did choose that as the markup language.

In no particular order, some things I don't like:

Ordered lists

. First item in the list.
. Second item.
+
Here is some follow-on text to the second item.
. Third item.

I love when a markup language automatically increments numbers in a list, but using a single dot doesn't make semantic sense to me, unlike repeating 1. (like in Markdown) or #. (in reStructuredText, another markup language). I also hate having to "attach" follow-on paragraphs with the + character. It makes the whole thing look cluttered, and visually I don't associate the follow-on with the list item it belongs to.

Compare this to the same list in reStructuredText (RST):

#. First item in the list.
#. Second item.
   Here is some follow-on text to the second item.
#. Third item.

Yes, you have to be more careful with whitespace, but the whole thing looks much more like what it will render to.

Links

https://example.com[Link text]

Having the URL followed by the link text is harder to read and looks messier. There is also no option to do reference-style links, where you defer defining the link URL to later in the document. Reference-style links make paragraph text easier to read and let you collect all link definitions in a single place, making them easier to find and update if needed.

Compare. AsciiDoc:

**JSON Schema** describes how some piece of JSON should be structured. For a good explanation, see https://spacetelescope.github.io/understanding-json-schema/about.html[What is a schema?] (from the https://spacetelescope.github.io/understanding-json-schema/index.html[Understanding JSON Schema] book).

Markdown:

**JSON Schema** describes how some piece of JSON should be structured.  For a good explanation, see [What is a schema?][what-is-a-schema] (from the [Understanding JSON Schema][json-schema-book] book).

[what-is-a-schema]: https://spacetelescope.github.io/understanding-json-schema/about.html
[json-schema-book]: https://spacetelescope.github.io/understanding-json-schema/index.html

RST:

**JSON Schema** describes how some piece of JSON should be structured. For a good explanation, see `What is a schema?`_ (from the `Understanding JSON Schema`_ book).

.. _What is a schema?: https://spacetelescope.github.io/understanding-json-schema/about.html
.. _Understanding JSON Schema: https://spacetelescope.github.io/understanding-json-schema/index.html

Both the Markdown and RST versions use reference-style links, making them easier to read.

Inline text styles

For reasons that I don't understand, the syntax for bold/italics/etc. is different based on whether you're applying it to the whole word or just part of the word, and different still if it's followed by punctuation. From Antora's documentation:

A word or phrase is marked as bold when it’s enclosed in a single set of asterisks (e.g., *word*) (constrained formatting). Bounded characters are marked as bold when they’re enclosed in a set of double asterisks (e.g., char**act**ers) (unconstrained formatting). You don’t need to use double asterisks when an entire word or phrase marked as bold is directly followed by a common punctuation mark, such as ;, ", and !.

Compare the above to how the Sphinx docs talk about how to apply bold in RST:

Use two asterisks: **text** for strong emphasis (boldface).

The AsciiDoc syntax seems unnecessarily complicated, and it probably doesn't even matter, because I can't imagine someone needing to use styles like this… but it still bothers me.

Docusaurus

After nearly three days of working on my Antora site, I turned to Facebook's Docusaurus. Two hours later, I had a functioning, attractive site running.

Docusaurus is only slightly older than Antora. It was released in December 2017 after being developed as the documentation solution for Facebook's open source projects.

Getting started

Docusaurus was a pleasure to use from the start. Their docs are brief, but include everything you need. The installation process looks like this:

1. Install NPM.

2. Run a quickstart script to generate a site.

3. Run the site with npm start.

I'm simplifying things — but not by very much. It was incredibly easy to set up a minimal site. After installation, I followed the Creating your site guide to learn where to put my source files, make the small changes needed to my existing Markdown (adding a page ID and title), list the files in a sidebars.json file to form a table of contents, and change some things like site name and theme colors. And just like that, I had a branded site with some content in it.

Configuration

Almost everything about Docusaurus is configurable in a single file: siteConfig.js. The file itself is well commented, making it easy to follow even without documentation. Compare to Antora, where the documentation on the equivalent configuration file, antora.yml, spans 11 pages (at time of writing). And you can't change the look-and-feel of your site with this file.

Features I like

Besides ease of use, what I like most about Docusaurus is that it adds documentation-specific features that were always lacking in Markdown (but present in Sphinx/RST).

Dynamic links

You can link directly to a page ID rather than filename, which allows you to move or rename a file without risking breaking all your existing links to that file.

At the top of each file, you define the page ID:

---
id: getting-started
Title: Getting Started with My Product
---
Body text here...

Then in another file, you can link to that file like so:

... for instructions, see the [getting started guide](getting-started)...

Table of contents

Markdown doesn't have a native way to construct a page hierarchy and order. You can manually write a list of links and serve that as your landing page, but that doesn't provide any real navigation, and you have to manually update page titles in your link list if they change. Docusaurus lets you add files by filename to a sidebars.json file, and builds your site navigation from that. You can even add categories within the sidebar. For example, Getting Started, Guides, and API here:

Admonitions

Admonitions are pre-styled callouts for "warning," "tip," "note," etc. Docusaurus only has a single option that uses Markdown's block quote syntax, but it's better than nothing.

Conclusion

Antora's creators might argue that there is a learning curve, and if I'd just spent more time and read through the (extensive) documentation more thoroughly, I'd find Antora to be a good tool. That may be true. The documentation was comprehensive, sure, but wordy in places, and there was too much of it — and that's probably because the tool is too complicated. This is a trap I've seen before — using documentation to work around an unintuitive product. When users struggle with a new feature, rather than changing the feature, you write several pages of docs explaining how to use it.

In our particular case, this is especially problematic. As a small internal documentation team, we don't have scores of tech writers who are only too eager to learn the nuances of the Antora directory structure and meticulously maintain navigation files. We need our documentation system to be as easy as possible for developers to contribute to. If they get frustrated with the Antora build or AsciiDoc syntax, they are likely to leave the system entirely and go back to writing documentation on the wiki or in Google Docs.

For ease of use and ramp-up time, Docusaurus was the clear winner. Markdown’s syntax is also more beginner-friendly than AsciiDoc’s, and while Markdown has fewer documentation-specific features, Docusaurus compensates for that by adding functionality like sidebar navigation and dynamic links.

To learn how Sphinx stacked up against both Antora and Docusaurus, see my next post.

(Bonus: I have more to say about Antora. If you’re interested, see my follow-up post.)

Why I love my smart light setup and how you can have one too

I didn’t understand the enthusiasm for home automation initially. Who could be so lazy that they can’t get up and turn off the lights like a normal person? The answer, it turns out, is me.

A friend eventually sold me on one feature -- with smart lightbulbs that change color, you can set your lights to be more reddish at night, avoiding the blue light that will keep your brain wakeful and making it easier to fall asleep. (It also doubles as mood lighting -- everyone looks good in dim red light.)

This was the hook that pulled me in, but I’ve come to love it for other reasons. Imagine that it’s winter and you’re cozily parked under a lot of blankets, watching TV in bed. When your eyes start closing, what if instead of having to venture out into the cold and cross the room, you could just announce to your digital servant Alexa that you want the lights turned off? Or imagine you wake up in the middle of the night and desperately need to pee -- do you stumble across the room, switch on the light, shield your eyes from the blinding beams, and try to pee as fast as possible so you can get back to bed? What if instead you could simply mumble, “Alexa, turn on nightlight,” and behold, the barest possible amount of light illuminates your path to the porcelain throne?

This is the reality I live in. The future is here, and it is pretty sweet.

In this guide, I will lay out step by step how you can set up your own smart light system, requiring no technical knowledge.

Assumptions

I live in a studio. My guide assumes that you are setting this system up for a studio apartment or two to three small, connected rooms. Bigger apartments or houses will require additional work, but that’s outside of the scope of this guide.

Because I know the products that I myself own, those are the ones I’ve written about. There are alternatives for each. Instead of an Amazon Echo, you can use a Google Home. There are other smart bulbs; even other color-changing smart bulbs, such as the LIFX Gen 3 mentioned by this Wirecutter article. If you’re interested, you can research the alternatives, but my assumption is that you’re reading this post because you just want straightforward instructions on setting things up. So you’re stuck with my choices!

I also assume that you want to use the color-changing feature of the bulbs. If you just want dimmable white lights, those bulbs will be a little cheaper and you can skip the “scene creation” steps of this guide. But then you won’t be able to turn your home into a disco.

What you’ll need to buy

• An Amazon Echo -- any size will work. I have an Echo Dot, the smallest one. There’s no real reason to buy a bigger one, but you can if you want to. $49.99 at Best Buy

• A Philips Hue White and Color Ambiance A19 Starter Kit. At time of writing, this comes with the hub and 4 bulbs. It only came with 3 bulbs when I bought it! You’re so lucky! $199.99 at Best Buy

• (Optional) Additional Philips Hue White and Color Ambiance A19 bulbs, depending on how many lights you have, how many rooms you want to rig up, and how much you’re willing to spend. They’re $50 each. I’ve read that you can buy used bulbs on eBay, so that is an option if you’re feeling thrifty. $49.99 each at Best Buy

Other things you’ll need

• Wifi

• A smart phone

• (Optional) A Google account. It makes signing into the various services easier if you connect your Google account rather than making new logins for each

Procedure

Part 1: Decide where you’re going to put stuff

The Philips Hue hub must be close enough to your wireless router to connect to it with an ethernet cable. Both the hub and the Echo must be plugged into a wall outlet. Plan this out beforehand and decide where you’re going to place both devices.

Part 2: Install the bulbs and the hub

1. Open your Philips Hue starter kit! Admire the stuff.

2. Turn off your lights at the wall switch.

3. Unscrew the old, boring, non-smart light bulbs from your lamps.

4. Screw in the Hue bulbs.

5. Turn your lights back on.

6. Plug the Hue hub into the wall.

7. Plug one end of the included ethernet cable into the Hue hub and the other end into your wireless router. Wait for the three blue dots on the top of the hub to light up.

Part 3: Connect your phone

1. Download the Philips Hue smart phone app from either the App Store (iPhone users) or the Play Store (Android users).

2. Launch the app on your phone and sign in with your Google account.

3. Tap Set up. It should prompt you to press the big button on the top of your hub to pair them.

Part 4: Find and name your lights

1. Once your hub is paired, tap the + button in the app to add a light, then tap Search. It will scan for any smart bulbs in the area.

2. Tap one of the lights in the list. The actual, physical light should blink.

3. Tap the i icon next to that light to go to the info about that light. On the info screen, rename the light so you can remember which light it is. (For example, I have “entryway,” “overhead,” “bathroom,” and “bedside.”)

4. Continue to name all your lights.
   
   Tip: To add more lights in the future (for example, if you buy some new bulbs later on because you can’t get enough), go to Settings > Light setup in the app and tap the +.

Part 4: Create a room

1. Once you’ve added all your lights, the app should prompt you to create a room. Tap the + button.

2. Name your room.
   
   Note: I only use a single room. Again, I live in a studio, and this makes it easier to control all the lights in my apartment with a single command. You can create multiple rooms if your space is bigger, but keep in mind that you’ll have to use multiple voice commands to control multiple rooms.
    

3. Choose a room type. (This step doesn’t matter much. It mostly determines the icon that will be displayed next to your room name.)

4. Next, uncheck any lights that you don’t want to be in this room.

5. Add more rooms by tapping the + again, or tap Next if you don't want to create any more.

Part 5: Create a scene

Now the fun part. You can create a specialized scene, like my orange-ish, dimmed “sunset lights,” or you can simply set the color and brightness that you want your normal lights. This is nice if you don’t want glaring, fluorescent lighting as your default.

1. In the Hue app, tap the room you want to create a scene for, then tap New scene.

2. Tap the name field to rename your scene.

3. Choose from one of the three bubbles at the bottom:
   
   * The picture option lets you select a color from within an image (either one of Hue’s presets or a picture from your camera). I have never used this option.
   
   * The white option lets you pick from the white light spectrum.
   
   * The color option lets you pick any color of the rainbow!

4. Move the slider under the scene name to set the brightness.

5. Save your scene.
   
   Tip: You can control each light in your scene individually. For my nightlight one, for example, I have only the bedside and bathroom lights illuminated.

Part 6: Set up IFTTT

IFTTT (“if’t”) is a utility for creating applets. You can think of an applet like a very simple program -- “if this happens, do this other thing.” (The name itself is an acronym for If This, Then That.) Congratulations! You’re now a programmer.

You’re going to use it to trigger your Hue hub to change the lights when you tell Alexa a command.

1. Download the IFTTT app from either the App Store (iPhone users) or the Play Store (Android users).

2. Launch the app and sign in with your Google account.

3. Tap the My applets tab in the bottom left.

4. Tap the + to create a new applet.

5. It should present you, as promised, with a form that says if this then that. Tap the this, then tap or search for Amazon Alexa.

6. Tap Say a specific phrase, then enter the name you gave your scene. (It doesn’t technically have to match, but I find it easier to remember and debug if I use the same name in both places.) Tap Create trigger to save.

7. Tap the that, then search for Philips Hue.

8. Tap Set a scene in a room.

9. Select the scene you just created from the dropdown list, then tap Create action.

10. Try it out! Say “Alexa, trigger <scene name>.” She should respond "Sending that to IFTTT," and the lights should change.

11. Try saying "Alexa, turn on <scene name>" instead. I can't find the article where I originally read this, but at some point in the last year or so there was an update (I think on the Alexa side) that simplified how you invoke IFTTT applets. Instead of saying "Alexa, trigger," you should be able to just say "Alexa, turn on," which sounds more natural. If you try this and it doesn't work for you, please let me know in a comment! It's possible I added some extra piece somewhere to enable this and have forgotten about it.

Note: If you want to customize the whiteness/brightness of your default lights, as I mentioned earlier, create a scene for that, then make an IFTTT applet whose trigger is just “lights.” Then you can say “Alexa, turn on lights” to get the default lighting you want. Note that if you say “Alexa, turn on all lights” (a built-in command), it will illuminate the lights at the last scene you had going before you turned them off. (“All lights” is just an on/off toggle, not a scene.)

Part 7: Repeat

Now you know the process: create a scene, set up an IFTTT applet, then order Alexa to do your bidding! Make as many scenes as you like.

Bonus ideas

If you add a smart home hub (like Harmony Hub, $79.99) to the mix, you can get really fancy. It can control any device with a remote control or wifi access. I use it to tell Alexa to turn on my air conditioning and my TV; with a Roku or Chromecast or similar, you can get even more specific: “Turn on Hulu,” “Turn on Netflix.” You can even use it to voice-control play/pause while you’re watching something on a streaming service, but I find the delay inconvenient (it takes several seconds to actually pause it).