Rename library

[agjohnson]

Before we start using this on user projects/publicly, readthedocs-client
sounds like a CLI or API wrapper, and we've called this the doc embed JS so
far. There's probably wisdom is reusing that naming or something similar.

[humitos]

I'd like to differentiate this library from the actual readthedocs-doc-embed.js file. I see this library as something new, completely different to what we have been doing. Besides, it may be deployed together with the old library based on a feature flag or opt-in by users. So, differentiation here will help us and our users to understand what's the integration they are using.

I'd propose looking for names that convey what it does. Something like the followings:

• readthedocs-integrations
• readthedocs-tools
• readthedocs-toolbar
• readthedocs-features
• etc

Note
We are using "embed" for our EmbedAPI as well, which has nothing to do with the readthedocs-doc-embed.js script. That's another reason why I want to differentiate here and use something that does not has "embed" on its name.

[agjohnson]

Good points! I like something like readthedocs-tools, though that has overlap with build tools 🙃

I think readthedocs/doc-tools or readthedocs/doc-utils are good targets. I like the narrative of "things we add to your documentation to make it better".

I've been throwing these types of questions to OpenAI and tune the outputs. It gave some good ideas for direction:

• readthedocs-tools
• doc-utilities
• readthe-utils
• rtd-helpers
• readthedocs-helpers
• doc-helpers
• doc-tools
• document-tools
• readthedocs-utilities
• document-utilities
• document-helpers
• rtd-utilities
• documentation-tools
• readthedocs-resources
• doc-resources
• readthedocs-support
• documentation-utilities
• documentation-helpers

[humitos]

I like the narrative of "things we add to your documentation to make it better".

Yes, yes, yes! I've been thinking think for a while now, since I wrote https://github.com/readthedocs/reports/pull/20#discussion_r1042075502 when talking about the 2023 roadmap 💯

• ✨make-my-docs-better.js 😅

In fact, how much marketing-y we want to go? What about something like 🤩 readthedocs-superpowers.js 🦸or something similar in that direction?

[agjohnson]

Hah, I was also thinking of something goofy like that, I'm definitely not opposed! Let's ask the AI.

[agjohnson]

Me and the AI went off the rails a bit, but it gave a few fun ideas:

• doc-powerups
• doc-booster
• doc-juice
• doc-sauce
• doc-magic
• doc-boost

🙃

There is definitely a product discussion in here though, and probably not something we need to consider just yet, but it is great to keep this in mind for later. We need to determine if we will be using injection of a group of features into documentation as a marketable feature, or is what we're marketing the individual features and injection is merely a technical implementation detail.

I might lean a bit towards the latter right now, but I do think we'll need some language for the group of features that we are inject.

[benjaoming]

readthedocs-embed-client or readthedocs-embed-client-js ?

[benjaoming]

I think I like readthedocs-integrations or readthedocs-helpers most of all the current candidates. They carry a certain aspect of the potentially UI-heavy aspect of the library. Since its for online websites, it could be called readthedocs-web-integrations

If called readthedocs-helpers, I could see spinoffs like readthedocs-helpers-sphinx and readthedocs-helpers-mkdocs.

[humitos]

@benjaoming

readthedocs-helpers most of all the current candidates

@agjohnson

I think readthedocs/doc-tools or readthedocs/doc-utils are good targets

I'd prefer to not use things like helpers, utils, tools or similar. Those names usually convey the meaning "I'm not sure where to put this function, so let's create a utils file" 😄

If called readthedocs-helpers, I could see spinoffs like readthedocs-helpers-sphinx and readthedocs-helpers-mkdocs.

We should not have files for specific doctools, since the idea is to be agnostic regarding to that.

---

The more I think about this, the more I like something like readthedocs-superpowers.js which communicates it's about Read the Docs, it gives some extra power/features to your site and it's a good marketing name, IMO.

I think I will move forward with it unless you are oppose on that.

[benjaoming]

I didn't think that readthedocs-superpowers is a thaaat good as a name :) I know that we know the complexity involved in it and why it's great. But for a small menu in a corner, the feeling of "underwhelmed" might occur :)

If you get your superpowers from mate, then I like readthedocs-mate... people that know the drink will think "juice" and people that read it as Australian will see it as a companion, which is also a really good name :) + the emoji exists :) It's a bit abstract, but it seems that the exact scoping of what the library does has made it hard to choose a normal name.

---

Those names usually convey the meaning "I'm not sure where to put this function, so let's create a utils file" smile

I think it fits very well with what this library is? A home for all client-side stuff? Do you worry that functionality that isn't at home in the library would end up here?

Because otherwise I think this is what it is: A lot of utility/helper functionality with no distinct theme. Some of it does UI, some of it does API calls, some of it is related to version logic, some of it is related to toggling the diff viewer.. lots of stuff!

We should not have files for specific doctools, since the idea is to be agnostic regarding to that.

It was a bad example to show that the naming convention looks nice if you want to have an extension, but no I agree that we will have a hard time maintaining multiple libraries, so it's nice to just have 1 library for everything 👍

---

readthedocs-menu would be another suggestion.. just to say what it is in the bigger picture. Most people can understand this as the library that inserts the menu. Everything else can seem secondary?

[agjohnson]

Good input! I'm enjoying this exercise 😄

I think at very least it sounds like we all do not want to keep client correct?

"I'm not sure where to put this function, so let's create a utils file"

Hah this is great point, lets scratch those.

A lot of utility/helper functionality with no distinct theme

Though I still do agree somewhat here too. In the end, it's a group of features that we're trying to lump together. I'd agree we can maybe avoid catchall sounding names though

readthedocs-menu would be another suggestion

The trouble with options like this is that we want to describe all of the features we're including in documentation, and the flyout is just one of those features that users might enable.

The more I think about this, the more I like something like readthedocs-superpowers.js

Documentation "superpowers", "powerups", "juice", "mate" are all great ideas to jump off from, but for the name of a product/feature these do probably feel too gimmicky. I'm still considering all these more from the product/marketing side foremost. For each of these we'd be telling users something like "Go to your project Settings, then Superpowers (Powerups/Mate/etc), and enable the flyout".

This is where it starts to feel odd for me, they all feel out of place.

However, I think what we're describing with these could be a great framing for a marketing page! It's not too over the top for a marketing page at all.

---

It's maybe only a small upgrade from docs-tools, but I was thinking yesterday how "Doc addons"/doc-addons would be a better fit for these features. It doesn't have the same "catchall" sound, is specific, clear, and we wouldn't feel odd telling users "Go to your project setting, Addons, and enable the flyout"/etc.

And I'd say that the marketing push could absolutely include some of the ideas that we've thrown around here.

[benjaoming]

addons is a great name, and just to be clear, would you say then that the project and package would be called doc-addons or readthedocs-addons? And why would you prefer one to the other?

[agjohnson]

Great question, this is one of the remaining points I'm not yet settled on. I guess I was suggesting Doc Addons as a feature name, doc-addons the library/repo/etc name. But probably only because it's a little bit more clear what function the addons serve -- they add on to docs, as opposed to add on to something undefined.

But that's just a guess too. Do others pull the same interpretation from just "Addons"?

[benjaoming]

I would think that prefixing with readthedocs makes it more clear what the library is really doing, i.e. connecting to RTD APIs. I would worry that doc-addons is really generic and would make it look like it's not a Read the Docs specific thing... but it is? :)

[benjaoming]

Also not completely impossible to call it readthedocs-doc-addons but then there's the docs-doc confetti, which is too silly :)

[agjohnson]

When we add HTTP proxy support for injecting HTML template snippets it could be called readthedocs-docs-socks-blocks-addon 😂

I would worry that doc-addons is really generic

I guess to elaborate:

• readthedocs/docs-addons - repo here
• @readthedocs/docs-addons - npm package name
• readthedocs-docs-addons.js - web bundle name
• etc

So, RTD would be part of the name in most use cases still.

But, also, I'm not strongly advocating here, just a note.

[benjaoming]

I'm not so worried about having the readthedocs prefix in the repo name. It's called django/django etc. People clone and fork it and then they can recognize what it is without manually renaming.

[ericholscher]

I think we arrived at Addons for the name here -- I say we should probably rename this library here soon, so we can start using it properly!

[humitos]

• readthedocs/docs-addons - repo here
• @readthedocs/docs-addons - npm package name
• readthedocs-docs-addons.js - web bundle name

@agjohnson @ericholscher are we OK with these names? I can do the rename if so.

[agjohnson]

Yeah, those names are good still I feel. If anyone has strong opinions otherwise, my main concern is mentioning addons and using the same name everywhere, give or take a symbol or two.

[ericholscher]

Any reason not to just say readthedocs/addons? Not sure if the docs is adding much?

[agjohnson]

Aye, I had the same thought above and don't feel strongly either way

• readthedocs/addons - repo here
• @readthedocs/addons - npm package name
• readthedocs-addons.js - web bundle name

That seems solid as well 👍

[humitos]

readthedocs/addons - repo here

✔️

@readthedocs/addons - npm package name

I created the readthedocs organization at https://www.npmjs.com/org/readthedocs

readthedocs-addons.js - web bundle name

• PR at Rename library to use "addons" everywhere #74 here
• PR in org at Addons: rename library readthedocs.org#10531
• PR in ops at https://github.com/readthedocs/readthedocs-ops/pull/1372

I also re-upload the js file as https://readthedocs-static-prod.s3.us-east-2.amazonaws.com/javascript/readthedocs-addons.js

I think we have everything in place now.

[ericholscher]

Awesome -- I'm glad we're using the same name in the code as in the marketing, that always helps make it easier to understand and communicate. 👍

[agjohnson]

I created the readthedocs organization at https://www.npmjs.com/org/readthedocs

@humitos I think this invite doesn't work for me because my NPM account is using my personal info. I keep getting failures accepting the invite. Could you send to NPM user agjohnson or [email protected]?

[humitos]

@agjohnson done!

[agjohnson]

Hrm, actually, it was the same effect: "Invitation was revoked" 🤷

Though, what is odd, is this is after it prompts me to accept the invitation into the RTD organization. It clear finds the invitation, and we know it's not revoked ... 🤔

I'll note to bug you about this again when I'm back, it's not really critical at all. In fact, I mostly think we'll just use the namespacing while internally working with the packages, but perhaps there will be a time we install everything through NPM

[pradyunsg]

FWIW, as an outside of group collaborator-ish person, I like this new name (and +1 on the naming consistency as well)!