Editorial Guidelines


These are a work in progress, but will serve as a starting point for now.

Working from Slack conversations is a little tricky, but our goal is to distill the discussion into a few key takeaways that are useful to our readers. It’s more important that our stories are clear and practical, than that we’ve recounted the conversation in its entirety.

The other thing to keep in mind is that, while we are paraphrasing from conversations we (probably) didn’t participate in, we want to be on guard against the temptation to editorialize. Try not to let your personal opinions sneak into your articles too much. And if there are two (or more) sides that come up in a discussion, we want to cover all of them as even-handedly as possible.

One last big picture thing, before we hit a few nuts-and-bolts points: Remember that the newsletter is governed by the WTD Code of Conduct just like any other part of the community. (In fact, even more strenuously since it’s coming from the organization directly.) So if you run across anything that’s even minorly dicey, with regards to the CoC, omit it from your story.

Some notes on the mechanics:

  • Each story should be 250 words maximum

  • Titles are in sentence case

  • Hyperlinks should be plain text (i.e., use descriptive text, rather than the URL, to attach the link to)

  • The proper, branded capitalization for WTD is ‘Write the Docs’, with a lowercase the. (This note is mostly here for Kelly O’Brien’s benefit, because she can’t remember to save her life.)

  • Linking to outside resources is great (blog posts, podcasts, online guides, etc.)

  • Avoid direct quotes from participants

    NOTE: If there is something you feel strongly we should quote, we’ll need to check with the person first, and then attribute it.