zulip
zulip copied to clipboard
zulip
Update 'Documenting REST API endpoints' docs.
Current Behaviour
On visiting /documentation/api.html#how-it-works
The first paragraph says:
To understand how this documentation system works, start by reading an existing doc file (api_docs/render-message.md is a good example)
Similar thing, in the first paragraph of /documentation/api.html#parameters
But there is no such file -- api_docs/render-message.md
In https://github.com/zulip/zulip/commit/23b991a80106a1d673e387fc7ec11e44b8a8d748 , we removed render-message.md in favour of using a common template.
Expected Behaviour
We should update the paragraphs to -- "start by reading api-doc-template.md and /messages/render endpoint in zulip.yaml" or something better.
Hello @1010nishant!
Thanks for your interest in Zulip! You have attempted to claim an issue without the label "help wanted". You can only claim and submit pull requests for issues with the help wanted label.
If this is your first time here, we recommend reading our guide for new contributors before getting started.
Hello @iSatVeerSingh!
Thanks for your interest in Zulip! You have attempted to claim an issue without the label "help wanted". You can only claim and submit pull requests for issues with the help wanted label.
If this is your first time here, we recommend reading our guide for new contributors before getting started.
Hello @iSatVeerSingh, it looks like you've currently claimed 1 issue in this repository. We encourage new contributors to focus their efforts on at most 1 issue at a time, so please complete your work on your other claimed issues before trying to claim this issue again.
We look forward to your valuable contributions!
Welcome to Zulip, @1010nishant! We just sent you an invite to collaborate on this repository at https://github.com/zulip/zulip/invitations. Please accept this invite in order to claim this issue and begin a fun, rewarding experience contributing to Zulip!
Here's some tips to get you off to a good start:
- Join me on the Zulip developers' server, to get help, chat about this issue, and meet the other developers.
- Unwatch this repository, so that you don't get 100 emails a day.
As you work on this issue, you'll also want to refer to the Zulip code contribution guide, as well as the rest of the developer documentation on that site.
See you on the other side (that is, the pull request side)!
@Aryanryn09 This issue cannot be claimed, as someone else is already working on it. Please see our contributor guide for advice on finding an issue to work on. Thanks!
@Tusharjolly21 This issue cannot be claimed, as someone else is already working on it. Please see our contributor guide for advice on finding an issue to work on. Thanks!
@iSatVeerSingh
I think, it is not a good practice to add help wanted and good first issue tags yourselves. It is mostly done by maintainers.
@alya please have a look at this issue. This needs some discussion regarding the actual wordings we should have.
Hello @zulip/server-api members, this issue was labeled with the "area: documentation (api and integrations)" label, so you may want to check it out!
@iSatVeerSingh I think, it is not a good practice to add
help wantedandgood first issuetags yourselves. It is mostly done by maintainers.@alya please have a look at this issue. This needs some discussion regarding the actual wordings we should have.
Indeed.
I'm not the right person to help with wording here -- @laurynmm could you take a look at this one?
@prakhar1144 - Thanks for the ping! Yeah, it's definitely not great that we reference a file that no longer exists.
As I was reading through all of this section to write up a summary of the changes that needed to be made, I felt like it was going to be just as much time as me doing a quick revision pass. I've got #24667 as a rough draft of updates to this section and would appreciate folks feedback / thoughts.
