Skip to content

docs: add a guide for writing product updates - #533

Merged
jumboduck merged 1 commit into
mainfrom
7982-5-product-updates-guide
Nov 12, 2026
Merged

jumboduck merged 1 commit into
mainfrom
7982-5-product-updates-guide

Conversation

@jumboduck

Copy link
Copy Markdown
Contributor

Add a guide for writers of the product updates page, linked from the page's template comment, the README and CLAUDE.md. The Kosli app now shows these entries in its What's new menu, and an entry's id and tags decide how it shows there and to which organizations, which nothing explained.

Part of kosli-dev/server#7982

🤖 Generated with Claude Code

The Kosli app now shows the entries of the product updates page in its
What's new menu, and an entry's id, rss fields and tags decide how it
shows there and to which organizations. Nothing told a writer that,
so a changed id would make an entry unread for everyone again, and a
mistyped tag would show a flag-gated entry to every organization.

The guide lives in docs/, which is not published, and is linked from
the page's template comment, the README and CLAUDE.md. It names the
server file that maps tags to flags rather than the flag keys, as the
repo is public.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jumboduck
jumboduck requested a review from a team as a code owner November 12, 2026 12:12
@jumboduck

Copy link
Copy Markdown
Contributor Author

Notes for review

  • The guide is in docs/, which .mintignore keeps off the site.
  • It names PRODUCT_UPDATE_TAG_FLAGS in kosli-dev/server rather than any LaunchDarkly flag key, as this repo is public.
  • Known tags today: new-navigation, new-trail-page. Any other tag shows the entry to every organization.
  • Not run locally: mint broken-links, as Mintlify does not support Node 26. No site links changed. pytest tests passes.
  • The page still holds two test entries (test-entry, test-entry-2, tagged test). They will show to every organization once the What's new menu is turned on, so they need removing before then.

@mintlify

mintlify Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
kosli 🟢 Ready View Preview Nov 12, 2026, 12:12 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@claude

claude Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @jumboduck's task in 39s —— View job


Doc review

Scope: docs/writing-product-updates.md (new), changelog/product-updates.mdx, README.md, CLAUDE.md. docs/ is in .mintignore, so the new guide is not a site page and doesn't need a config/navigation.json entry. I couldn't check the server-side claims (PRODUCT_UPDATE_TAG_FLAGS in src/lib/feature_flags.py, the five-minute poll, the twelve-month unread cutoff) because they live in kosli-dev/server.

docs/writing-product-updates.md

  • Suggestion — Location: docs/writing-product-updates.md:19-28
    Issue: The "Copy this shape" example uses the real published entry's id="new-navigation" and tags={["new-navigation"]}. If a writer copies it as-is, they ship a duplicate id and the entry only shows to organizations with the new-navigation flag on. The template comment in product-updates.mdx already uses placeholders.
    Recommendation: Use placeholder values (id="your-feature-name") and either leave out tags or point to the tag table. Fix this →

changelog/product-updates.mdx

  • Suggestion — Location: changelog/product-updates.mdx:32-64 (this PR doesn't change these lines)
    Issue: According to the new guide, an unknown tag "is ignored, and the entry shows to every organization." The two test entries are tagged test, so every organization with the What's new menu turned on sees them.
    Recommendation: Remove the test entries before the menu reaches customer organizations, or register a server-side tag for internal-only entries.

2 suggestions, 0 critical, 0 improvements. Advisory only. Nothing here blocks the merge.

Comment thread docs/writing-product-updates.md Resolved
@jumboduck
jumboduck enabled auto-merge (squash) November 12, 2026 12:15
where that flag is off. When the flag is turned on for an organization later, the entry
shows there as unread.

These are the tags the server knows:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the current list and would need updating as we add more things?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mbevc1 Correct. Maybe we should not have this list here.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, if this is going to change we should either reword this or remove it from here, because it's a high risk of rot

@jumboduck
jumboduck merged commit 0898cf7 into main Nov 12, 2026
6 checks passed
@jumboduck
jumboduck deleted the 7982-5-product-updates-guide branch November 12, 2026 12:20

This branch was successfully deployed

1 active deployment
staging — 877472c7 Deployed Nov 12, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants