Writing effective documentation for Discourse

[maiki]

Heya Simon!

@simon

@Discourse

Use contractions: it’s, you’ll, you’re, we’re, let’s

Along with avoiding idiom, I always avoided using contractions in docs. I thought they made it harder for non-English/non-western readers to understand. English is a weird language.

I was going to see how this played out, but yeah I’m the same way, I try to avoid contractions.

@simon

@Discourse

Use transition words such as moreover, although, hence, and therefore

moreover?

Hahah, yeah… I’m not going to use any of those words in docs, lest I reveal my .

@simon

It might be worth using a consistent placeholder name to refer to Discourse sites. Maybe discourse.example.com? There’s some documentation on here that’s referring to the Discourse site as sitename.com. It really threw me off.

Definitely: Example Domains

@simon

As much as I appreciate no longer having a ton of doc topics ascribed to me, using Discourse as the author of all the team’s doc topics feels a little cold.

What’s made writing fun for me again was the advice to look for ways of putting a bit of yourself into whatever you’re writing. It could be anything, your tone of voice, your hobbies, whatever… That’s kind of the opposite of what’s being recommended here.

This is the point I came here to discuss!

We’ve had a lot of back and forth on this, and I was glad to see this included in the style guide by default.

Here’s why I think it is important: producing documentation needs to be accessible for as many members of our community as possible, including (especially?) our Discourse team members.

Discourse is social, discussion software. And some documentation is really an ongoing conversation. If I’m sharing a practice on how I onboard members to my community, I’d want to be presented as the “owner” of that topic, so I may answer questions and expand on the subject.

On the other hand, if a customer asks about a feature that we never got around to explaining, I would like to be able to use the style guide and produce useful, general documentation, which I feel being the topic owner presents more inertia to publishing.

Also, if we produce documentation outside of Discourse (an integration or producing from code comments or whatever), having a “documentation user” is likely easier as a implementation detail.

I don’t think this guide will stop folks from injecting their voice and personality, and hosting the discussion. But it would be great if it helps more people get into the practice of documenting, who would not otherwise (and then we can nudge them to be more personal!)