[wantab]

I'm working on integrating Braintree payments into a client of mine. Braintree is a perfect example of this and is a wolf in sheep's clothing, meaning, their docs look great at first glance until you need to get all the way through them.

For example, you start reading about how to do A. Half way through, you find out you need to do B. So you look at the link to B which then refers to C but C is A and you realize you're in a loop.

So then you try their search function, or Google, but then you find yourself linked to either outdated docs that look like the same thing or articles about the subject which give no detail.

It's spaghetti documentation mixed with out of date spaghetti mixed with meatballs. At this moment, I have 13 tabs open to various parts of the docs trying to piece things together to understand how to make it work and, sometimes, I find the out of date docs more understandable!

[gbramwell]

Hi, I'm one of the devs working on the Braintree docs. You're absolutely right, the information flow in our docs isn't in a great state right now.

We're actively trying to fix the flow issues by consolidating information so you don't have to go tab-hopping to find what you need. If all goes well, hopefully you'll see some improvements showing up very soon™.

If there's a specific problem you'd like to share, I'd welcome the feedback. Either way, we'll keep forging ahead on another rev that's a little easier to follow.

[jkoudys]

I had a similar experience with the Eventbrite API. The docs looked well-written, and early usage was promising, but then you have to get almost to the end of your implementation before realizing the missing components. In my case, EB allows what's called a "repeating event", or an event that occurs on multiple dates. However, their response JSON doesn't have anything like `{times: []}`, rather it's just `{start: {}, end: {}}`, so you never have a set of the dates. There _is_ a 'repeats: <boolean>' property in the response, but that is permanently set to false, and if you have a repeating date it appears as a single-date event where the start and end times are for the next upcoming date.

I would have been better off if they didn't supply that doc at all. If I just fumbled my way through an undocumented pile of service endpoints, I'd have realized its limits much sooner. The doc gave me the false-confidence to build my application based on behaviours in their API which aren't actually implemented.

[beerbajay]

Oh god, salt-stack is just like this. Lots and lots of documentation which looks great at first, but once you actually start using it it's frustration after frustration. The poor typography and use of YAML doesn't help...

[goatandsheep]

I always use archive.org to archive links so that if they break, I can always link back to them later.