Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion know-your-audience.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Your audience might be:
- End user relying on your product → may not be technical, looking to get started or how to do a specific task
- Developer responsible for integrating your product → needs clear and concise instructions to get to their goals

Ahead of writing any page, ask yourself: what is my reader trying to accomplish (see [Content Types](/content_types)) and what is their prior knowledge?
Ahead of writing any page, ask yourself: what is my reader trying to accomplish (see [Content Types](/content-types)) and what is their prior knowledge?

## User research is key

Expand Down
4 changes: 2 additions & 2 deletions writing-style-tips.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ description: 'Principles for style and tone'
>
> \- **CT Smith, Head of Docs at Payabli**

- **Don’t use product-centric terminology.** Your users don’t have the full context of your product (see [“Know Your Audience”](/know_your_audience)). Always orient language around the user’s familiarity with your product and what they’re trying to achieve.
- **Don’t use product-centric terminology.** Your users don’t have the full context of your product (see [“Know Your Audience”](/know-your-audience)). Always orient language around the user’s familiarity with your product and what they’re trying to achieve.
- **Avoid “Duh” documentation.** Don’t tell users “Click Save to save.” Documentation should add value, not outline obvious steps.
- **No colloquialisms.** Especially for localization, colloquialisms hurt clarity.

Expand All @@ -36,4 +36,4 @@ Leverage existing style guides to standardize your documentation:
- [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse)
- [Google Developer Documentation Style Guide](https://developers.google.com/style)

When you know which writing principles you want to implement, automate as much as you can. You can use linters (such as [Vale](https://vale.sh)) or your documentation provider, such as Mintlify’s [CI checks](https://mintlify.com/docs/settings/ci).
When you know which writing principles you want to implement, automate as much as you can. You can use linters (such as [Vale](https://vale.sh)) or your documentation provider, such as Mintlify’s [CI checks](https://mintlify.com/docs/settings/ci).