4 ms·

If you don't have a way to share documentation for your API with anyone for a cost of about $0.00, then you're signaling that your development process is a bit

If you don't have a way to share documentation for your API with anyone for a cost of about $0.00, then you're signaling that your development process is a bit broken.

madeofpalk 6y ago
its probably just a case of they emailed support@ without a support contract, and didn't get very far. I don't think that's very indicitive of much, especially for "enterprise software".
- thaumaturgy 6y ago
  Sure, but there's no reason for something like API documentation to require emailing support@. Let me cite a specific recent example: I was tasked with building an application that integrated document e-signatures. The spec called for Docusign specifically, so I looked at their documentation. What I could find of it was written unclearly and much of it was hidden behind a developer account login. Getting a developer account was "free", as long as my time was worth $0. (You had to fill out a form of some kind, I don't remember the specifics anymore.) So then I looked at HelloSign, a competitor. Their documentation was public, freely available, and beautiful (https://app.hellosign.com/api/documentation https://app.hellosign.com/api/documentation). It included specific examples and walkthrus. This says things to me like, "we care about the developer experience". I practically begged the customer to use HelloSign instead. I expected, from experience, that Docusign integration was going to suck, and HelloSign integration would suck a lot less. The customer said, "the spec already says Docusign, so we can't switch". And the Docusign integration did suck. It was terrible. Lots of it was incomplete. Their vendor library was a godawful mess, built from some automated tool that converts an API into a bad class library. Their support was basically useless even after a contract had been negotiated and signed. The client ended up spending an extra ten grand or so and at least a couple weeks worth of delays just on Docusign-related issues. This is a pattern that reoccurs often enough that experienced developers use documentation as a proxy for the quality of the service.
  - jaywalk 6y ago
    Your example is comparing apples to oranges. We're talking about software that doesn't even have "contact us for pricing" on the website because nobody that needs it even asks what it costs.
    - thaumaturgy 6y ago
      Sorry, I don't talk to enterprise ISVs unless somebody's paying my billable rate.
  - madeofpalk 6y ago
    Developers will not be shopping around, making the decision to buy a ‘global manufacturing suite’ like DELMIA Apriso, whatever that is. If they are, they will have the documentation made available for them.

If you don't have a way to share documentation for your API with anyone for a cost of about $0.00, then you're signaling that your development process is a bit broken.

madeofpalk 6y ago

its probably just a case of they emailed support@ without a support contract, and didn't get very far. I don't think that's very indicitive of much, especially for "enterprise software".

thaumaturgy 6y ago
Sure, but there's no reason for something like API documentation to require emailing support@. Let me cite a specific recent example: I was tasked with building an application that integrated document e-signatures. The spec called for Docusign specifically, so I looked at their documentation. What I could find of it was written unclearly and much of it was hidden behind a developer account login. Getting a developer account was "free", as long as my time was worth $0. (You had to fill out a form of some kind, I don't remember the specifics anymore.) So then I looked at HelloSign, a competitor. Their documentation was public, freely available, and beautiful (https://app.hellosign.com/api/documentation https://app.hellosign.com/api/documentation). It included specific examples and walkthrus. This says things to me like, "we care about the developer experience". I practically begged the customer to use HelloSign instead. I expected, from experience, that Docusign integration was going to suck, and HelloSign integration would suck a lot less. The customer said, "the spec already says Docusign, so we can't switch". And the Docusign integration did suck. It was terrible. Lots of it was incomplete. Their vendor library was a godawful mess, built from some automated tool that converts an API into a bad class library. Their support was basically useless even after a contract had been negotiated and signed. The client ended up spending an extra ten grand or so and at least a couple weeks worth of delays just on Docusign-related issues. This is a pattern that reoccurs often enough that experienced developers use documentation as a proxy for the quality of the service.
- jaywalk 6y ago
  Your example is comparing apples to oranges. We're talking about software that doesn't even have "contact us for pricing" on the website because nobody that needs it even asks what it costs.
  - thaumaturgy 6y ago
    Sorry, I don't talk to enterprise ISVs unless somebody's paying my billable rate.
- madeofpalk 6y ago
  Developers will not be shopping around, making the decision to buy a ‘global manufacturing suite’ like DELMIA Apriso, whatever that is. If they are, they will have the documentation made available for them.