riboseinc / ribose-api

API for Ribose
0 stars 0 forks source link

Make heading structure more consistent across sections #25

Open ribose-jeffreylau opened 6 years ago

ribose-jeffreylau commented 6 years ago

Currently, our API doc is inconsistent in that the headings for our plural and singular resources don't follow one set of convention. E.g., for Calendar and Wiki, they use the "Resources" (plural) - "Resource" (singular) heading pair, while for other sections, well, they don't seem to follow any convention.

It would be great if they would all follow the "Resources" - "Resource" convention:

(See: https://developer.veeqo.com/docs#/reference/orders for ideas. They use the "Resource Collection" - "Resource" pair instead, but I think it's a matter of personal preference.)

skalee commented 6 years ago

I opt for longer titles, e.g. "Delete a calendar", not just "Delete", or "Deleting". It's easy to lose oneself in long documents, and it really helps then.

ronaldtse commented 6 years ago

Agree with @skalee -- better description the better!