Flagsmith / Flagsmith/flagsmith
docs: Standardise integration articles
- 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
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