3 ms·

Before I left Square earlier this year, I lead our design efforts on the developer API. https://docs.connect.squareup.com/ https://docs.connect.squareup.com/

Before I left Square earlier this year, I lead our design efforts on the developer API. https://docs.connect.squareup.com/ https://docs.connect.squareup.com/ It was really interesting work and the team was quite committed once we found the right team. People always asked what does a designer do on an API. It turns out that if the team cares, quite a lot. Documentation is the obvious one but lots of other things like structuring the actual information, setting up apps, working on API explorers, look at terminology even how the endpoints are thought of and of course, how do you easiest get up and running with the API. It was surprisingly interesting work from a design point of view.

tabeth 9y ago
Square has excellent developer documentation! Hopefully it's in good hands after you've left. It would suck if the quality degraded.
- ThomPete 9y ago
  Glad you like it. It's in good hands indeed.
cyberferret 9y ago
Great documentation - I am looking to document our own SaaS app API in the coming months, and am inspired to follow Square's lead in terms of style and structure. Did you use a third party documentation CMS for that, or roll your own internally for all the formatting etc.?
- ThomPete 9y ago
  A combination. The actual API Reference is using a documentation CMS the other stuff is home-brewed.
yeukhon 9y ago
+1 Perhaps I have said this before, but UX folks have been my go-to colleagues whenever I need their inspsirations for anything ranging from graphs (like monitoring metrics) to debugging since the UX team is heavily involved from the inception of a project and sometimes have more intimate knowledge of the overall architecute of the project than the core developers do. They are amazing (of course I am talking about the right kinds).
- ThomPete 9y ago
  And I have it the same way with developers. They were always my go-to colleagues more than other designers for insights and I would generally suggest to hang out with radically different perspectives than your own. Luckily, in my new company both my partner feel the same way.
  - yeukhon 9y ago
    Right! Worth sharing I am a DevOps so I do production support. One night I was at the dinner table fixing some horrible issue. My sister and brother-in-law asked why I was frowning. Initially I refused to explain the situation but they convinced me to brief them the failure. They raised some questions as outsiders (one is a doctor, another is an accountant). Immediately lightbulb lighted up! Within minutes I was able to find the root cause, pushed a fix, documented the issue, and closed my laptop.
    - ThomPete 9y ago
      Exactly
eric-hu 9y ago
It's been years since I've consumed a square API, but I found it amazing when I did. Thank you for your work, even if it came after I used it. Do you think that the Square API hit the level of design just because of the people involved? Or are there organizational factors that played into it? I.e. was good API design seen at the top as a good reason to take longer with a release? I really want to find suggestions to take into my company.
- ThomPete 9y ago
  A combination. From the day I started back in 2012 it was clear to me that in order for us to grow functionality to enough verticals in the merchant space we would have to build an API as that was the only way to actually allow for the platform to grow beyond what we could build internally. It was a hard push for a while though as the focus was in some of the other areas that made us actual money. The first inception had a pretty strong team but less backup in the organization. We did a lot of great work that never saw the light of day. Then the last couple of years it all changed and there was suddenly a push to do proper API I was "called into duty" again. This time the foundation was product led rather than tech led and that changed things a lot. My personal experience was that people just saw API as some technical curiosity rather than as an actual foundation for the business. Luckily plenty of people in the organization was aware of its importance. This has changed a lot the last couple of years I think not the least because of Stripes documentation which is almost legendary today. For some reason, I was always aware of its importance. I even wrote an essay about it back in 2009 and wrote: "The next big battle is going to be a battle between digital ecosystems; not gadgets, not products and not services. The most important weapon is going to be the WMCs: Weapons of Mass Connection, a.k.a. the APIs. These APIs will make it possible for different organizations to have data flow freely between them. Allow for anyone with the right idea to leverage on others’ success without taking anything away from them. On the contrary, the more trusted interpreters you can give access to the data flow, the more robust the digital ecosystem will be." http://000fff.org/the-power-of-digital-ecoystems/ http://000fff.org/the-power-of-digital-ecoystems/

tabeth 9y ago

Square has excellent developer documentation! Hopefully it's in good hands after you've left. It would suck if the quality degraded.

ThomPete 9y ago
Glad you like it. It's in good hands indeed.

cyberferret 9y ago

Great documentation - I am looking to document our own SaaS app API in the coming months, and am inspired to follow Square's lead in terms of style and structure. Did you use a third party documentation CMS for that, or roll your own internally for all the formatting etc.?

ThomPete 9y ago
A combination. The actual API Reference is using a documentation CMS the other stuff is home-brewed.

yeukhon 9y ago

+1 Perhaps I have said this before, but UX folks have been my go-to colleagues whenever I need their inspsirations for anything ranging from graphs (like monitoring metrics) to debugging since the UX team is heavily involved from the inception of a project and sometimes have more intimate knowledge of the overall architecute of the project than the core developers do. They are amazing (of course I am talking about the right kinds).

ThomPete 9y ago
And I have it the same way with developers. They were always my go-to colleagues more than other designers for insights and I would generally suggest to hang out with radically different perspectives than your own. Luckily, in my new company both my partner feel the same way.
- yeukhon 9y ago
  Right! Worth sharing I am a DevOps so I do production support. One night I was at the dinner table fixing some horrible issue. My sister and brother-in-law asked why I was frowning. Initially I refused to explain the situation but they convinced me to brief them the failure. They raised some questions as outsiders (one is a doctor, another is an accountant). Immediately lightbulb lighted up! Within minutes I was able to find the root cause, pushed a fix, documented the issue, and closed my laptop.
  - ThomPete 9y ago
    Exactly

eric-hu 9y ago

It's been years since I've consumed a square API, but I found it amazing when I did. Thank you for your work, even if it came after I used it. Do you think that the Square API hit the level of design just because of the people involved? Or are there organizational factors that played into it? I.e. was good API design seen at the top as a good reason to take longer with a release? I really want to find suggestions to take into my company.

ThomPete 9y ago
A combination. From the day I started back in 2012 it was clear to me that in order for us to grow functionality to enough verticals in the merchant space we would have to build an API as that was the only way to actually allow for the platform to grow beyond what we could build internally. It was a hard push for a while though as the focus was in some of the other areas that made us actual money. The first inception had a pretty strong team but less backup in the organization. We did a lot of great work that never saw the light of day. Then the last couple of years it all changed and there was suddenly a push to do proper API I was "called into duty" again. This time the foundation was product led rather than tech led and that changed things a lot. My personal experience was that people just saw API as some technical curiosity rather than as an actual foundation for the business. Luckily plenty of people in the organization was aware of its importance. This has changed a lot the last couple of years I think not the least because of Stripes documentation which is almost legendary today. For some reason, I was always aware of its importance. I even wrote an essay about it back in 2009 and wrote: "The next big battle is going to be a battle between digital ecosystems; not gadgets, not products and not services. The most important weapon is going to be the WMCs: Weapons of Mass Connection, a.k.a. the APIs. These APIs will make it possible for different organizations to have data flow freely between them. Allow for anyone with the right idea to leverage on others’ success without taking anything away from them. On the contrary, the more trusted interpreters you can give access to the data flow, the more robust the digital ecosystem will be." http://000fff.org/the-power-of-digital-ecoystems/ http://000fff.org/the-power-of-digital-ecoystems/