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 exhaustive list of SDK configuration options or API routes, refer to references.
Documentation Review Workflow
**Why review? **Docs are part of the product. If the docs fail to get functionality across users get less value and we get more support requests. In the past we’ve seen docs pages to be hard to understand for people who did not build the product.
When do I need a review?
- No hard rules here, it’s up to you to decide if changes were major or you think the 2nd pair of eyes makes sense. (We are happy to take a look in any case!)
- Suggestion: if you added a headline (h2,h3) showing in the “on this page” might be still worth a review
- If you are doing a changelog post we suggest you request a review in any case
Workflow
- Decide if you need a docs review at all and if it should be before or after feature release (see above)
- Assign Felix Krauth or Jannik Maierhoefer as review on the Docs change PR - they commit to same day reviews. If it’s too late in the day then the next morning.
- In most cases we will just release the docs for you and notify you, in some cases we might sync back to you
FYI: the review is much faster / easier for us if we see the diffs pre-release and then just release
Changelog Review Workflow
**Why review? **If your code / feature is world class but nobody understands why they need the feature or lack the instructions to get started your code creates less value.
Workflow
Info: We suggest to rather have less sync between feature release & changelog posts than to not have a review! If the changelog posts are not on point on first look we leave adoption on the table.
- Basically same process as Docs Review above, just assign @felix or @jannik as reviewers on PR, we will do same day review
- We can also create marketing ready gifs / images for you ( so you can consider just delegating that to us )
Common issues we spotted in the past:
- Links to the wrong internal documentation pages
- New Docs Page did not reference the new feature directly - no “on this page headline” in docs or even ability to cmd+f search on page
- New feature that lived mostly in UI did not have a screenshot / gif which made it hard to understand where the user could find it and try it out
- Most Changelog posts require the knowledge of already existing users vs. potential future users
What we want to achieve with changelog posts
- People who are using Langfuse should get new value by start using the new feature
- People who are considering LF for some time finally see the features from their wishlist and get started because of it
- People who are not using Langfuse should think “this team ships”