Editorial guidelines¶
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: 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 close to the line with regards to the CoC, omit it from your story.
Some notes on the mechanics:
- Each story should be 250 words maximum. We do sometimes allow longer articles if there’s a lot of valuable content, but in general try to stick to this.
- Titles are in sentence case.
- Hyperlinks should be plain text: 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. But the acronym is WTD, all caps. - Linking to outside resources is great (blog posts, podcasts, online guides, etc).
- We don’t have a strong preference for American vs British English, but try to consistently stick to one of them.
- Avoid direct quotes from participants (the Chatham House Rule.) If there is something you feel strongly we should quote, check with the person first, and then attribute it.
- It’s okay to have one article in an edition that is mainly a list, and two isn’t terrible, but be careful with this. We don’t want all our newsletters to be just listicles.
