Documentation

“Documentation is product” and we care a lot about it as it helps us efficiently scale to a large and growing community. Docs are maintained by Product Engineering and GTM teams together; the owner of a product feature/area is responsible to keep docs in order.

How to make edits to Langfuse Documentation

The documentation page (and website) is in the langfuse/langfuse-docs repo. Follow the README.md to set up the project on your local machine. Make changes via Pull Requests. Anyone can make changes, contributions welcome.

How to write good technical documentation?

• Be clear about your objective and audience
• Include links to other related documentation pages
• Start high-level for novice users and incrementally build up customization/complexity when needed
• Familiarize yourself with diataxis and the difference of:
  • Tutorials
  • How-to Guides
  • References
  • Explanations
• For an exhaustive list of SDK configuration options or API routes, refer to references

Good reads:

• leerob.com/docs
• Posthog How we write docs?
• Mintlify Docs Guide

Redirects when moving or renaming pages

When you move or rename a documentation page, always add a redirect from the old URL to the new one. This preserves user experience (bookmarks, shared links) and SEO (search engines transfer ranking to the new URL).

Where: All redirects live in lib/redirects.js. Next.js and Cloudflare Pages both use this file.

How:

1. For page moves/renames, use permanent redirects (they are applied as 301 so search engines update their index).
2. At the bottom of lib/redirects.js, add a new dated constant (e.g. myPageMoveRedirects202601) with a short comment describing the change.
3. Add one or more [oldPath, newPath] tuples. Paths are relative to the site root (e.g. /docs/evaluation/data-model → /docs/evaluation/experiments/data-model). You can include hash fragments for specific sections (e.g. "/docs/foo#section").
4. Spread your new constant into the permanentRedirects array.

Important: Permanent redirects can only be added, not removed (browsers and search engines may cache them). Use a descriptive constant name and comment so future readers understand why the redirect exists.

Example prompt for Cursor / Claude Code: You can ask the AI to add redirects for all page changes on your current branch. Copy-paste something like:

Look at the git diff on my current branch for the pages/ directory. For every file that was moved or renamed (or whose path changed), add a permanent redirect in lib/redirects.js: old URL → new URL. Use the same pattern as existing redirects: create a new dated constant (e.g. myChangeRedirects202601) with a short comment, add [oldPath, newPath] tuples (paths relative to site root, e.g. /docs/foo not pages/docs/foo.mdx), and spread it into the permanentRedirects array. Only add redirects for pages that actually changed path; do not add redirects for edits to existing files.

Changelog

For new capabilities and updates, we write changelog posts.

Motivation:

• People who are using Langfuse should get new value by starting to use the new feature
• People who’ve been considering Langfuse for some time finally see the features from their wishlist and get started because of it
• People who aren’t using Langfuse should think “this team ships”

Documentation/Changelog Reviews

The owner of a feature/area is responsible to maintain its documentation.

Sometimes it’s hard though to write good docs if you are very much in the weeds. Felix and Jannik are happy to help with PR reviews to get the docs right.

No hard rules here, it’s up to you:

• If changes were major or you think a 2nd pair of eyes makes sense (we’re happy to take a look in any case!)
• If you added a headline (h2, h3) showing in the “on this page,” it’s probably worth a review
• If you’re doing a changelog post, usually getting a review is a good idea

Steps:

1. Decide if you need a docs review and if it should be before or after feature release
2. Assign Felix or Jannik as reviewer on the docs change PR - they commit to same-day reviews. If it’s too late in the day, then the next morning.
3. In most cases, we’ll just release the docs for you and notify you; sometimes we might sync back