Consolidate current API tool documentation

[stumblefiend]

The current API content we have is sparse and extremely spread across many pages when one page on API tools would rank better for SEO, provide more value and better findability for our visitors, and lower our site footprint and content management overhead.

If we can expand the API tooling content in the future, this new, consolidated API page can become the index / topic cluster that future API tooling pages can link to.

I read through https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role and https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#internal-links but could use extra eyes on the links in this pull request. Actually, please tell me how to test the links myself or point me to the documentation I should use for testing links for the site. I couldn't find any suggestions on testing before creating the PR in either of the contribution guides:

• https://github.com/writethedocs/www/blob/main/docs/guide/contributing.rst
• https://github.com/writethedocs/www/blob/main/docs/guide/learn-git-contribute.rst

---

📚 Documentation preview 📚: https://writethedocs-www--2169.org.readthedocs.build/

[plaindocs]

I'll take a look at some of these minor issues, and the links

[plaindocs]

@stumblefiend once you've got a passing build, broken internal links will break it. You'll get the same info running Sphinx locally, but a lot of folks just push things up to GH and fix when the build break. And you can click these links to see more details:

[stumblefiend]

Thanks for the clarification and help. Much appreciated! In the future, rather than run the linter and sphinx locally, I'll just fix whatever the build errors complain about. I'm on a Chromebook anyway and my Linux terminal won't even open half the time for me to run these tools locally in the first place 😅

[plaindocs]

Sounds good - @ tag me if you run into any trouble.

[stumblefiend]

Who needs to provide final review in order to merge this PR?

[plaindocs]

I can 👍 it later today

[CollierCZ]

Given that API Blueprint doesn't have active maintainers (reference), do we really want to actively promote it as one of our favorite descriptive languages? I would also note that we shouldn't be referring to Swagger format anymore.

Dredd also seems mostly abandoned (people are considering forking it), so I'm not sure if any of the information on the new page is actually useful now (though I'm sure it was previously).

I appreciate the idea of consolidating and I hate to block positive moves, but increasing the chance of people seeing outdated information might not be a net positive. If we're going to increase the number of people seeing it, it might help to check if it's relevant.

[stumblefiend]

Let's document these valid concerns but continue evaluating this PR.

We weren't in the top 100 search results for much of anything related to API anyway. @CollierCZ your point is one of the reasons why. We can continue to implement this pull request because it is an incremental step towards reconsidering our API content.

I will file a github issue relating to your 100% valid concerns about the state of our API documentation. I definitely think that content validity is a high-priority item to address ASAP. I've noted this in my own backlog of optimizations I'm spearheading as well.

[CollierCZ]

I don't think that the outdated nature of the content is what is hurting SEO. I also don't think that trying to increase traffic to outdated content is a good strategy for SEO.

As I see it, all of the content on the new page is outdated, meaning it is low in quality, something that hurts SEO in the long run. I don't think that consolidating low-quality content into one page is actually an incremental change for the better.

In my opinion, it'd be best served by removing outdated content and keeping #2171 for putting in relevant content.

[plaindocs]

@CollierCZ I get where you're coming from! Replies over on the relevant issue.

But I also think that merging this PR is lower effort than refactoring the existing content out, and therefore is an improvement.

[stumblefiend]

Thank you all for your thoughts and energy in consideration of this PR.

I'm reminded of the joys of housecleaning...you sweep small things into a pile and then you finally see how badly the house was in need of cleaning after all.

[stumblefiend]

Looks like I can't merge anything since I don't have write access. Can one of you grant me write access since I have a lot of PRs planned?

[CollierCZ]

I think sweeping up a house is a good metaphor there. And then you don't leave what you've swept up in a pile that you invite everyone to look at, but put it in the 🗑️ . 😉

The lowest effort moving forward (and in my opinion biggest improvement) would be deleting the new page and keeping the rest of the PR (meaning the content would be gone). 🤷

I don't think I can grant write access. I'm just a member of the org.