: 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?
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.
1 Comments
Sorted by latest first Latest Oldest Best
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.
Terms of Use Privacy policy Contact About Cancellation policy © selfpublishingguru.com2024 All Rights reserved.