# Writing effective documentation for Discourse

**URL:** <https://meta.discourse.org/t/writing-effective-documentation-for-discourse/309628>\
**Category:** Contributing\
**Tags:** reference\
**Created:** [May 28, 2024, 4:24am UTC](https://meta.discourse.org/t/writing-effective-documentation-for-discourse/309628 "2024-05-28T04:24:22Z")\
**Posts on this page:** 1\
**Showing post:** 12

<div class="post-metadata">

**Author:** ![maiki](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/maiki/32/233950_2.png) [@maiki](https://meta.discourse.org/u/maiki)\
**Post date:** [May 31, 2024, 10:15pm UTC](https://meta.discourse.org/t/writing-effective-documentation-for-discourse/309628/12 "2024-05-31T22:15:06Z")

</div>

Heya Simon! :blob_wave:

> [@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](https://www.iana.org/help/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!) 😃

---

_[View the full topic](https://meta.discourse.org/t/writing-effective-documentation-for-discourse/309628)._