Flagsmith / Flagsmith/flagsmith

docs: Standardise integration articles

Open
#6,771 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
6.6k
Forks
567
Avg merge
1d 14h
Merged PRs (30d)
124

Description

Most — likely all — Flagsmith integrations included in our documentation will need the same structure:

- What to expect
- How it works
- Pre-requisites
- How to setup

The content in each of the above sections will vary according to each integration, but the structure should be very similar.

We're expected to see increased quality in content and contribution, and decreased time in reviewing documentation, if we adopt patterns to guide integration docs.

For example, rather than having discussions [like this](https://github.com/Flagsmith/flagsmith/pull/6755#discussion_r2848720147), we could standardise on a way to cite pre-requisites to configure an integration:

> ## Pre-requisites
>
> - An **Organisation API key**: obtain from _Organisation settings > API keys_ in Flagsmith.
> - The **Project ID**: obtain from the Flagsmith dashboard URL, e.g. `/project//...`.
>
> [!NOTE]
> **Enterprise users**: when generating the Organisation API key, select permissions {permissions}, so that {integration} can {action}.

---

## Acceptance criteria

- Write a template for third-party integrations that include the standard sections and default content. Writers can start from a booster right into writing text and adding screenshots.
- Include placeholder for screenshots in the template throughout the sections where applicable. These must be the minimum accepted screenshots in an article. Adding more screenshots is recommended.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing third-party integration articles and the linked pull request discussion to identify the current structure and recurring prerequisites or screenshot needs. Done means a reusable integration template exists with the four named sections, default guidance, and minimum screenshot placeholders.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.