getsentry
rfc(feature): Versioned docs
This RFC proposes the implementation of versioned documentation for Sentry Docs. The goal is to provide users with access to documentation specific to different versions of a Sentry SDK. Currently, users only have access to the documentation of the latest version of a SDK.
I am not sure if I agree with you @rahulchhabria Yes, we can combine the logged-in state to pre-select the version. But don't think if we don't this right away it's a blocker or too complex for people to understand - so I wouldn't tie those two problems together.
Now, my feedback for the RFC:
I think we should also think about providing versions for not just major version bumps. What if we add new features in a minor with a new preferred way we want users to use it? Then we should also be able to reflect that somehow. If we need to copy an entire folder for every minor change we want to render, it might quickly become overwhelming.
Can we figure out a solution to version individual files/pages, not entire folders?
With duplication of code this will make maintaining the prose text in the documentation harder, and the same page in different versions will diverge. This is something we need to keep in mind. Most of the times we want the pages to be different because something changed in the new version. But if we want to update the wording, we need to make sure we do it in all versions.
Another thing (maybe not fully related to this RFC).
I would love to render the "options" sections from source code. We could add this documentation to the source and then render the mark down file from the source. So we would not need to update the code and the docs pages separately, but only update the code and if there are new options or new documentation for an existing option, the documentation is updated automatically.
I saw this a while back, wonder if we could use it to render parts of our docs from source: https://til.simonwillison.net/python/cog-to-update-help-in-readme
Another thing (maybe not fully related to this RFC).
I would love to render the "options" sections from source code. We could add this documentation to the source and then render the mark down file from the source. So we would not need to update the code and the docs pages separately, but only update the code and if there are new options or new documentation for an existing option, the documentation is updated automatically.
@antonpirker So you would want to render the options version specific from source I assume?
Can we figure out a solution to version individual files/pages, not entire folders?
@HazAT with option 3 we would do basically that. We could for example add the version to filename and use that for displaying different versions of the same page. Or do you think it would make sense to do the versioning within a file (maybe something with a <Versioned version="1.1.1">... component?
Another thing (maybe not fully related to this RFC). I would love to render the "options" sections from source code. We could add this documentation to the source and then render the mark down file from the source. So we would not need to update the code and the docs pages separately, but only update the code and if there are new options or new documentation for an existing option, the documentation is updated automatically.
@antonpirker So you would want to render the options version specific from source I assume?
Yes exactly. But I think this is not really related with this RFC. However we decide on organizing the versioned docs, we then can add some code or github action or whatever, to render the options page for the right platform and the right version accordingly
Would this let us write docs for next/future versions, or is that out of scope?
