4 ms·

UI's a funny term for APIs. I don't think it's that complex. APIs are written documents describing external controls to a system's behavior. A good document c

UI's a funny term for APIs. I don't think it's that complex. APIs are written documents describing external controls to a system's behavior. A good document can describe both the controls and behavior clearly and succinctly. A bad one can describe the same in long and convoluted language that effectively hides the underlying system. Often in a mess of "should" and "can" clauses, with lots of passive voice, vague assumptions, and unnecessary complexity and verbiage. For some reason, I feel many programmers write documentation the same way that they wrote their X-page essays for English class. They're just trained to write fluffed-up junk that fills some imaginary requirements of a long-irrelevant class. EDIT: To clarify: I'm describing the actual types and methods themselves. They infer an underlying mechanism and a means to control it.

matt_kantor 10y ago
What you're describing is an "API reference". APIs are the external controls themselves, the things that you're documenting in the reference. I think it's reasonable to say that APIs are UIs. They are how users and/or machines interact with a system.
GavinMcG 10y ago
An API isn't the document - it's the interface. (That's what the "I" stands for!) One which developers use, which would make it a type of UI even though it's not necessarily the UI that's exposed to end users. And that's kind of the point: the documentation should certainly be clear and well written, but the necessity of all that can be minimized by carefully designing the way developers can work with your tool in the first place.
- lallysingh 10y ago
  Every identifier in the system is a bit of documentation. I submit that there's a difference when you name a function: bool ufklsjblsboabfds(int, int) and bool operator<(int, int) I know that to many, the idea of individual identifiers being documentation is a bit radical, but I think it's the first documentation a developer sees. It's the documentation built into the body of every piece of code that they read and write.
  - GavinMcG 10y ago
    > I know that to many, the idea of individual identifiers being documentation is a bit radical I think the opposite – it's totally mundane to most people. Aside from the intellectual exercise it requires, people don't have any reason to use a language that used bool ufklsjblsboabfds(int, int) any more than they would use Brainfuck. So, sure, the API "documents" the functionality in the most minimal way possible. But when you say "documentation" you're using a term that almost no one will understand in the way you mean it.

matt_kantor 10y ago

What you're describing is an "API reference". APIs are the external controls themselves, the things that you're documenting in the reference. I think it's reasonable to say that APIs are UIs. They are how users and/or machines interact with a system.

GavinMcG 10y ago

An API isn't the document - it's the interface. (That's what the "I" stands for!) One which developers use, which would make it a type of UI even though it's not necessarily the UI that's exposed to end users. And that's kind of the point: the documentation should certainly be clear and well written, but the necessity of all that can be minimized by carefully designing the way developers can work with your tool in the first place.

lallysingh 10y ago
Every identifier in the system is a bit of documentation. I submit that there's a difference when you name a function: bool ufklsjblsboabfds(int, int) and bool operator<(int, int) I know that to many, the idea of individual identifiers being documentation is a bit radical, but I think it's the first documentation a developer sees. It's the documentation built into the body of every piece of code that they read and write.
- GavinMcG 10y ago
  > I know that to many, the idea of individual identifiers being documentation is a bit radical I think the opposite – it's totally mundane to most people. Aside from the intellectual exercise it requires, people don't have any reason to use a language that used bool ufklsjblsboabfds(int, int) any more than they would use Brainfuck. So, sure, the API "documents" the functionality in the most minimal way possible. But when you say "documentation" you're using a term that almost no one will understand in the way you mean it.