Remove project description field

[agjohnson]

Plan

• Remove description from project import form
• Remove description from project settings form
• Remove description from project detail display
• Leave description field on model and API return

Discussion

I think we have good reason to just remove the description field. The dashboard page is public, but is not a reader focused page. This is extraneous UI for a maintainer dashboard page.

Having said that, we should evaluate what pulling this out looks like -- specifically:

• Can we simplify the import forms more by removing the description field?
• Does it make more sense to remove from modeling and just remove from forms and templates for now?
• What does the project dashboard page look like without a description block
• What % of projects have a description field

[davidfischer]

41% of our projects have a description. More than I thought! Among our featured projects on the homepage roughly half of them had a description and most of those were one-liners.

In [2]: Project.objects.all().count()
Out[2]: 80360

In [3]: Project.objects.exclude(description=None).exclude(description='').count()
Out[3]: 33073

The dashboard looks fine without the description I'd say:

I'm +1 on removing the description from our forms. I'm not sure it adds much value. I'm +0 on sourcing it from elsewhere (github, etc.)

[humitos]

I'm 👍 on removing the description also.

I suppose that not too many people read it.

Although, I maybe we could support (in the future) a setting in the YAML file, something like:

description:
   file: README.md

and

description:
   content: "My description goes here"

Anyway, using the YAML or "just sourcing by default" will require a decision regarding what branch use for this (I suppose it could be default_branch).

On the other hand, having a configurable option in the YAML like this for a feature that is not really used (as reader) maybe is not a good idea.

[ericholscher]

I guess my only thought about removing it is losing the ability for projects to specify status on the description. The primary use case I worry about losing is the "This is unmaintained" or "This project is now located here" or "this is a fork of XYZ" or similar.

I think having a description is quite a small bit of overhead, and there is a lot more valuable refactors we could be doing. I'd be curious on the pitch of the value of removing it.

I'd be +1 on limiting the size to ~500 chars, so it doesn't break UI. The "Sync from YAML" solution is part of a much larger discussion about how to manage DB & YAML based state going forward, that we need to choose a solution and execute on.

I also think there is a larger conversation to have around removing more from the admin dashboard/edit pages, including the "Project Homepage" and probably a few other bits of state that don't matter.

[ericholscher]

I guess the other big reason to remove the description field is spam. If this is a spam fighting measure, I'm +100 for it, and think that's heavily worth the downside outcomes.

[humitos]

I liked to point that Eric raised here: "use the description field to communicate unmaintained projects" and that's important.

I saw other projects that has updated the whole documentation to just mentioned that the project was moved to another place. So, when you hit any page related to an old documentation you see just a link pointing to the new documentation page.

Another solution that I saw to this problem is a danger note added to each page.

So, even if we remove the description field we have other types of workarounds to solve that problem, the only difference is that they involves more time/coding than just change a description field.

[agjohnson]

I agree with @humitos on this, and think updating the docs is a better fix if a maintainer wants to stop updating their docs. The use case for deprecating your builds on RTD but not updating your docs to mention deprecation doesn't seem super likely.

I think we continue to view the dashboard page as a reader page, and it doesn't really function like that. Readers of a documentation project interact with the built project, not with our dashboard. This feels like have a README or description in your GitHub project admin dashboard. I suppose the natural extension of this, which I'd also be 👍 on, is making the dashboard 100% private -- so downloads and search end up on with a separate UX or as more direct links from doc pages. This is separate however.

I never saw much value in the description field, but I'm 👍 on removing because it will allow us to condense the front page UI and expand the version list if we need to. It's also used heavily for spam right now, so removing it removes a reason for spammers to attack us.

I probably wouldn't be enthusiastic about a README config parameter either, for the same reasons.

[agjohnson]

Oh and I suppose what i meant by "what does our dashboard look like" is not what does it look like if we remove the field, but how can we improve the page without the description block there?

I think a more vertical version listing table would be a great addition, adding some metadata about version builds (failed, built, branch name, default? latest? stable?), version "freshness", and view docs links. All this information would need more vertical stacking, so a missing description field frees up that space.

[bansalnitish]

@agjohnson May I give this a try!

[ericholscher]

I'm +1 on it then!

[humitos]

So, even if we remove the description field we have other types of workarounds to solve that problem, the only difference is that they involves more time/coding than just change a description field.

We could write a guide about this, inviting folks that don't want to maintain their documentation to make the last effort on communicating this properly to their readers.

[RichardLitt]

@bansalnitish I don't see why you wouldn't be able to! As far as I know, no one else is looking actively fixing this in a PR right now, which means it is open game. :)

[bansalnitish]

Thanks @RichardLitt, I am working on this!

[agjohnson]

@bansalnitish Also, just to clarify, you're welcome to take this issue up when it's ready. This ticket is still in a design decision process for right now. It would be best to wait until we've finished this process so that you aren't working on something that won't be merged.

[agjohnson]

@rtfd/core It sounds like we're on the same page regarding:

• We will remove the display from the project detail page
• We will remove the field from the project form
• We will remove the field from the admin dashboard form

Still undecided:

• Do we remove the description field in a migration?
• Do we remove the field from the API return (if it's there already)?

[humitos]

Do we remove the description field in a migration?

I'd say yes. If we are not going to use it at all, there is no need to keep this in the database, but...

Do we remove the field from the API return (if it's there already)?

We are returning it (at least in v2):

https://github.com/rtfd/readthedocs.org/blob/d127ea5ce2cca4bf8c74f1889125b851d987f382/readthedocs/restapi/serializers.py#L13-L26

Mmm... Removing this will be a breaking change. I see two options:

• keep the data in the database and return it here
• remove the column from the database and fake this field by returning the empty string '' or similar

[ericholscher]

Hmm. I think we can keep it in the DB for now, but just remove it from all places. Force an empty string in the API response.

I think its a good "stepped deployment". If we remove it from the DB, we can't roll back, so I'm more comfortable just hiding it as a first step, waiting a bit, and then deleting it, just in case there is a downside to removing it, or people want it back.

[agjohnson]

Keeping the field and hiding display/forms is a great solution for now, 👍 .

I also realized in #3754 that we are populating this automatically through GitHub/Bitbucket import, so that probably explains why so many projects have a description

[dojutsu-user]

Is this issue open?
I would like to submit a PR.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stsewd]

I think there is an open PR for this

[humitos]

@stsewd if so, please link the PR here and mark this issue as Accepted and put it into the right milestone. Thanks!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stsewd]

This is the PR #3754 (closed because of inactivity)

[dojutsu-user]

I am working on it.
Will submit a PR soon.

[dojutsu-user]

@stsewd @humitos
While working on this, I found that we detect Spam Projects through description field.

https://github.com/rtfd/readthedocs.org/blob/fcc89f436e508386817ce663b2a28d7e55d1b783/readthedocs/projects/forms.py#L177-L181

So, would it be okay to hide this field as this will remain empty for all the new projects and spam detection will not work.

[stsewd]

I'm not really sure that we use that at all, fighting spam is hard, and the description field is helping to have more space for spam, that's one reason why we want to remove it too :)

[stsewd]

Coming back to this... I think we may want to keep the project description, but making it just simple and short, this is, not support rst, and no more than 150 chars. The reason, is that a short description to find about what the project is about may be useful, and we are also using that to index search results for projects.

[ericholscher]

I'm 👍 on removing RST and shortening them. Seems like a good middleground.

[agjohnson]

I like the way that GitHub uses description:

I'd be +1 on a very basic text description field -- no reST, no markdown, we'll do link replacement. There might not be a good way to automatically migrate project.description to something like this though.

Our new templates do not have a place for the existing Project.description, I've removed it already. So the work left here is:

• Decide if we add a smaller description field like GH
• Decide what we do for projects that have an imported readme/etc for the project description
• Add a smaller description field back into templates @agjohnson
• Alter the edit form and modeling
• Migrate the display at the same time as template release? Or some reliable way to detect an old description field vs a new description field?

If we migrate at the same time as new templates, we can make the description field appear as a field that looks new to users, and it won't be as strange that we stopped showing the description field as it is in the project dashboard page now.

I'm also fine just removing it, migrating everyone to Project.description = None and adding something back sometime later. I still don't see a lot of value in the description field as the project dashboard pages are still mainly a maintainer feature, not a general reader user feature like GitHub dashboard is.

[davidfischer]

I'm also +1 on a basic description field. The only other note I'll add is that if we add any URLs that they should be rel="nofollow" to make sure they aren't a target for spammers.

[stsewd]

we'll do link replacement.

We already have the homepage attribute to link to the project, so I think we don't need to make link replace here.