4

This question is in reference to API documentation. Say the name of an object is "Action" in the backend, but "Step" in the UI.

We cannot rename objects.

My approach is to explain that Action = Step in the UI, and to use the term "Action" so that people are clear on the objects I am referring to (there are associated objects and filters, etc., such as "approved_actions").

My colleague believes that the better practice is to use terminology from the UI (and of course also to explain that Step = Action).

My thought process is that people making API calls will be more confused if we use UI terminology that doesn't match up to object names. Under each object is a description of what that object is in the UI as well already. I am considering repeatedly defining that in each section for index actions to appease him, but not sure it's really necessary. Any thoughts on this, especially for those experienced with API documentation?

2
  • 1
    Hi, welcome to writing.se! Take the tour and visit the help center for more information. While on-topic for this site you might have better luck asking this over at Software Engineering. It's a great questions and I hope you get some good answers.
    – linksassin
    Feb 5 '20 at 2:53
  • 1
    For API documentation, stick to API names. Be sure, though, to provide a dictionary to map API and UI terms, and every time you introduce a new API term, mention its UI equivalent.
    – Alexander
    Feb 5 '20 at 18:47
4

This happens all the time. Sometimes it's not even the programmers' fault. :-)

I agree that you must use the API names. After all, you are documenting what needs to be used in programming. Yes, you can mention the UI label -- which might even change at some point.

UI labels are meant to work for users, and they are constrained by space, localization concerns, style rules, and other considerations. API objects, commands and parameters need only be unique and (somewhat) readable.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.