Feedback Issue: Adding rails Endpoints to docs
Background
In this MR, we introduced a new documentation page to address the issue of incomplete documentation for our Rails endpoints. Previously, these endpoints lacked a designated place for their documentation, leading to confusion and occasional issues. While not all internal Rails endpoints may require documentation, the absence of a suitable solution caused problems.
Currently, our solution involves adding a markdown file for each Rails endpoint. However, we are open to exploring alternative approaches, including automation.
Proposed Solution
Our proposed solution is to consolidate all endpoints in a single markdown file located at doc/development/rails_endpoints/index.md. This approach offers a clear and comprehensive overview of all endpoints and their functionalities, ensuring easy accessibility for everyone involved. We believe this is the most user-friendly solution.
Alternative Approach: Automation
An alternative approach under consideration involves leveraging automation to generate and update the Rails endpoints documentation. This approach has the potential to save time and effort. However, we would like to gather feedback to assess if this is a preferred method, considering the potential downside of implementation complexities and accessibility challenges.
Trial Period
To adequately evaluate the alternative approach, we plan to implement it in trial mode for a duration of 90 days. Throughout this period, we will closely monitor its impact and gather feedback to assess its effectiveness.
Feedback Requested
We kindly request your feedback on the following points:
- What are your thoughts on the currently proposed solution of adding a markdown file for each Rails endpoint?
- Are you open to exploring an alternative approach that involves automation? If so, please let us know if you have any specific concerns or suggestions.
- Do you have any other suggestions or ideas regarding our Rails endpoint documentation?
An initial discussion took place on the MR with the BE maintainers. If you're curious about their thoughts on this matter, we encourage you to check it out.
Please share your thoughts, opinions, and any additional suggestions you may have. Your input will greatly contribute to improving our Rails endpoint documentation.
Thank you!