# 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:** 11

<div class="post-metadata">

**Author:** ![simon](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/simon/32/339122_2.png) [@simon](https://meta.discourse.org/u/simon)\
**Post date:** [May 31, 2024, 6:53pm UTC](https://meta.discourse.org/t/writing-effective-documentation-for-discourse/309628/11 "2024-05-31T18:53:06Z")

</div>

> [@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.

> [@Discourse](#):
>
> Use transition words such as _moreover, although, hence,_ and _therefore_

moreover?

> [@Discourse](#):
>
> General writing guidelines, tone, and grammar

At some point we (possibly me) started using inline code to refer to site settings. For example: “Enable the `discourse connect` site setting.” That might be the right approach, but it feels kind of developery.

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.

* * *

Some general writing advice: read what you’ve written as though you’re a member of your (see how contractions are tricky) target audience. Make sure your assumptions about the audience’s prior knowledge are reasonable.

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.

---

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