Change copy around "import project"

[agjohnson]

A minor copy issue that I've long had trouble with is how we refer to project creation as "importing a project". This copy is fairly minor, but it's use is pervasive, and in the interest in clarifying our UI and UX, it's not very accurate. In order to better communicate our platform, I think I'd rather refer to this process as "adding a project" and "connecting a repository", or "configuring" a repository to work with Read the Docs.

Some thoughts on the copy:

• We aren't "importing a project" -- the source is not "a project". You could maybe argue we "import a repository", but I think even that isn't accurate
• In many other UIs, "import" refers to a process that converts the format of a file/etc -- ie "Import from csv", etc. This describes a process that alters from the original format -- ie "Import from csv" means that your CSV file and your new file format are divorced from each other. This is the main reason the term has always felt incorrect to me. We aren't converting the repository at all, we only use the repository to configure a Project object.
• Other CI services use "configure a repository", or "add project"
• "Configure a repository" or "connect a repository" describes a much lighter process than "importing"
• Now that caching is removed, there is never a time that the on disk repository does not match the source repository

So, depending on the usage, I'd suggest that the new templates:

• Describe the action as "adding a project"
• Copy that describes our process instead refers to our process as "configuring a repository" or "connecting a repository"

Work required:

• Lots of templates updates where "import" is used in copy. This is my primary focus, and this can happen without code changes.
• Code changes:
  • URL changes
  • View/class name changes
  • Filename changes

Where does @readthedocs/core land on this?

[humitos]

I agree with you. However, I think the workload is important and the value my not be too much --but new templates are the right time to change this concept, so it makes sense to tackle this nowish.

How would we call a "project" after this change? For example, "Configure a repository" will create a Project object under Read the Docs and we will expose it with the name "project"? In that case, there is some discrepancy between repository and project. On the other hand, calling it repository requires a lot of changes in template/code and the main URL for them: /projects/<slug>/. Also, the differences between the templates and the code/URL/filenames could lead to confusions.

That said, I'd vote for some copy where we can still call it "project" but with a more accurate action. Probably, "Add a project" as you suggested, or "Configure a project", "Setup a project" or something close to that.

[ericholscher]

Yea, I like connect or add. 👍 I think we should continue with project as the noun, but definitely change up the verb.

[stsewd]

I'd be +1 on using add, short and clear

[agjohnson]

Great, I think "add" is much clearer. I'm not suggesting we alter what we call our models locally -- we still host a "project", which we "add" when configuring a new project. We don't host a "repository" so this makes sense. The magic part that we do is "connect to a repository" or "automatically configure a repository" which refers what GitHub/GitLab host (they use "repository"). So this is probably the most correct overall as well as the most clear language.

[agjohnson]

I have updated this already in the new templates. So what is left here for work is a long tail of doc updates, etc that backend team should feel free to contribute changes for. I'll keep this on the template roadmap for now, but there is nothing else that is actionable for the front end team at this point.

[agjohnson]

It seems we're all on the same page here about the terminology, but I did want to add to this to continue building some momentum to removing the term import from our lexicon and shaping our marketing messaging more.

I have realized that the main reason why import has felt very wrong to me is that import implies that we are storing a copy of the repository, as in we are importing it into our system. This was arguably the case at one point, but is not longer accurate. Instead, we have a direct connection to the source repository and we are continually using that connection. In fact, import misses on this point too, as import commonly implies a one-time process (ie "importing a CSV").

Anyways, just wanted to add more here as every time I come across the term Import project I want to tap this particular sign 🙂

[plaindocs]

Hey folks, this is a conversation to have. I'm definitely in agreement with either add or connect over import, and as shorter is better, add looks good.

You've got a new Dashboard to roll out with these changes, right?

In reference to updating the docs, I'd say something like the following vague order of descending importance,

• make the UI match the concept (ie update it to add)
• matching the term in the docs to the UI button people are gonna use (ie, update the tutorial heading and mentions of buttons)
• internal document consistency (the rest of the doc)
• doc site consistency (other scattered mentions around the docs)

[agjohnson]

You've got a new Dashboard to roll out with these changes, right?

Indeed! You can log in at https://beta.readthedocs.org and poke around

I'd say something like the following vague order of descending importance

👍 I'd say we're either a half step before or after that first step. The beta instance has updated these terms, but we haven't decided at what point we will start documenting it or when we make it the primary dashboard.