3 ms·
You’re thinking in a silo’d/tunnel vision manner. Consider different audiences. Devs, customer/user, support, sales. Yes, api definitions are in code, but wha
by flandish 4y ago
You’re thinking in a silo’d/tunnel vision manner. Consider different audiences. Devs, customer/user, support, sales.
Yes, api definitions are in code, but what our customers see is just as valuable.
If it’s not what they want, and they can’t support themselves with the doc we write we’ll be in a hellish back and forth with them.
Code is our love, and code can be GREAT at documenting itself.. but customers don’t ever want to view javadocs.
- nailer 4y ago> if we want to code correctly we need to write down and manage expectations with both our customers and ourselves I am assuming an audience of devs and customers / users of an SDK - ie people that need to understand the code. Support and sales (unless selling an SDK) should not see any code or code documentation at all.
- flandish 4y agoI am not sure of your experience or industry but while it is true customers/users don’t see code, they most *certainly* see documentation. In the form of “help->about” or user manuals, websites, or call center interaction. When I said “documentation is important” I meant all documentation and sometimes an engineer needs to document across scope boundaries. (IE: you should be able to describe where that file export api fits into the grand scheme in a way that gives a user what they -need- to know or gives support advice on how to fix issues.)
- nailer 4y ago> I meant all documentation OK I thought we were discussing code documentation. I think we see eye to eye on other types of docs.