Add API documentation link to front page

[dacharyc]

I've been thinking about the API documentation, and I'd like to get the link here on the docs front page as a starting point.

Bigger-picture, it would be good to create some cross-links to the documentation portal from the API docs, I think. The endpoints are all documented, but the API docs assume that people who are consuming them are familiar with how Tugboat works, and assume developers are familiar with what the docs mean when we say things like "projects" "repositories" "previews" "services" and "visual diffs."

I think an incremental improvement we could offer is to provide links from the API docs to the main docs site at the beginning of each API doc section for "concept" explanation, so we're not trying to maintain that info in two places. Currently, the "concepts" are documented inconsistently. For example, the Preview -> Reset and Preview -> Rekey POST commands have concept explanations, but the rest of the Preview POST commands lack them.

Short-term, I think we should add the Google Analytics Rollup ID to the API documentation so we have some idea how many folks are consuming it, and that info can help us prioritize when/how much work to put into improving the API docs.

[mettamatt]

Nice work, Dachary! Had you also considered linking to the API Documentation from the left sidebar as an alternate option in the Tugboat docs?

[dacharyc]

Had you also considered linking to the API Documentation from the left sidebar as an alternate option in the Tugboat docs?

Negative, @mettamatt . The sidebar in the Tugboat Docs takes you to specific pages within the Tugboat docs site; the way the Hugo site is structured, those links automatically generate from the section headers. I'm not manually populating them.

In order to be consistent with the way the docs site currently functions, we'd need to create a "page" in the Hugo site that the sidebar link would point to, and then that "page" could link out to the API docs, so it would be two clicks/ a level down for users to get to. That seemed like a worse option than just putting it on the front page.

The other option - manually adding a sidebar link that takes the user to the API docs portal (a different site) - is probably technically feasible, although I don't know how to do it, but it would be inconsistent with the way the rest of the links in that sidebar nav work. Every other link would take the user to a page in the docs site, but that one would take them to a different site. That's also bad UX.

I'd love to link out to the API docs at the beginning of each relevant section here in the docs portal (i.e. under the Setting up Tugboat -> Add Repos to the Project section, link to the relevant section of the API docs so users can see "Here's how you'd do this via the API") but the scope of that project would be much larger. I think I'd have to do a little fiddling to get a variable in the URL instead of linking directly to the v3 version of the API docs (presuming we'd always want the docs to point to the most recent version of the API, that version might change at some future point), and there's also the information architecture work of figuring out which pages on the docs site should link to which sections of the API docs.

An even bigger pipe dream is to automatically ingest portions of the API docs into the main docs site so we can display relevant chunks inline here, with links out to the API docs for code examples, etc. but, again, seems premature given we don't have any idea how many people are interested in consuming the API docs in the first place. I believe this can be done, but the scope of the project would be larger and I'd want traffic data to the API docs/API usage data to justify the effort.