: What to do when API objects and UI names are different? 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

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?

Load Full (1)

: When Should A Writer Stop Self-Editing? I have about four thoroughly edited unpublished novels right now, and I have accounted for a lot like: story (developmental editing), logic and consistency,

@Jessie137

Load Full 1 Comments

: APA In text citations, with the same first author and one other author with the same surname This seems to be a bit of a corner case. I have two articles, with the same first author, B.

@Jessie137

Load Full 0 Comments

: What is Considered to be a Large Portfolio to be Sent to Agents/Publishers? I am currently looking for an agent to represent a portfolio of books. But I was wondering, what is considered to

@Jessie137

Load Full 2 Comments

: The language and communication style used in instructional videos, How-To manuals, and lessons for beginners that provide practical information about a specific subject. A tutorial author might

@Jessie137

Load Full 0 Comments

Login to post a comment!

1 Comments

Sorted by latest first Latest Oldest Best

@Ravi5107385

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.

Load Full (0)

Feed

: What to do when API objects and UI names are different? 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

More posts by @Jessie137

: When Should A Writer Stop Self-Editing? I have about four thoroughly edited unpublished novels right now, and I have accounted for a lot like: story (developmental editing), logic and consistency,

: APA In text citations, with the same first author and one other author with the same surname This seems to be a bit of a corner case. I have two articles, with the same first author, B.

: What is Considered to be a Large Portfolio to be Sent to Agents/Publishers? I am currently looking for an agent to represent a portfolio of books. But I was wondering, what is considered to

: The language and communication style used in instructional videos, How-To manuals, and lessons for beginners that provide practical information about a specific subject. A tutorial author might

Login to post a comment!

1 Comments

Back to top