Skip to content

Add documentation on "Getting started with Read the Docs" #8329

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
agjohnson opened this issue Jul 8, 2021 · 4 comments
Closed

Add documentation on "Getting started with Read the Docs" #8329

agjohnson opened this issue Jul 8, 2021 · 4 comments
Assignees
Labels
Accepted Accepted issue on our roadmap Improvement Minor improvement to code

Comments

@agjohnson
Copy link
Contributor

We currently have guides on gettings started with Sphinx/Mkdocs, but don't ever describe how to get started using Read the Docs for new users who are completely unfamiliar with RTD. This might be something we wait on for new templates, as we likely want additional screenshots of the UI, and have two separate interfaces currently.

We do have some docs on importing a project:
https://docs.readthedocs.io/en/stable/intro/import-guide.html

This is a good start, and perhaps might even be sufficient, or could be a base to work from. I feel like we had some additional content in the past, but it doesn't seem very discoverable in our docs if it does still exist.

Some pieces that might be worth adding to our getting started documentation:

  • Signing up with VCS account and creating your first project from a connected repository
  • If the user doesn't have a repository to test yet, this is the point where they should do the Sphinx getting started guide
  • Setting up your project after you've gone through the Sphinx getting started guide
  • Configuring versions and version privacy
  • Your first build
    • Your first build failure
    • Dealing with common build failures

There is certainly a good amount of user-centric documentation (especially around smaller features) missing in our docs, but to keep scope here low, the goal of this work is to provide users unfamiliar with RTD a full description of getting started.

@agjohnson agjohnson added the Improvement Minor improvement to code label Jul 8, 2021
@astrojuanlu astrojuanlu self-assigned this Jul 8, 2021
@agjohnson
Copy link
Contributor Author

agjohnson commented Jul 8, 2021

This has some additional items: https://github.com/readthedocs/readthedocs.org/blob/master/docs/development/design/new-sphinx-guides.rst#read-the-docs-tutorial

A few additions I'd make to this list are:

  • We should cover handling build failures. This is a common hurdle we don't have documented
  • Feature documentation might be better as independent docs instead of guide content. We have localization docs that need updated, and could use independent docs on analytics.
  • Also, not mentioned yet, we haven't addressed any of the organization/team pieces in our docs at all either -- team management, adding users, etc

@humitos humitos added the Accepted Accepted issue on our roadmap label Jul 12, 2021
@astrojuanlu
Copy link
Contributor

In progress in #8428

@ericholscher
Copy link
Member

Should we call this done? 🎉

@astrojuanlu
Copy link
Contributor

Yay! @agjohnson mentioned a few extra items, I think we can address those over time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Accepted Accepted issue on our roadmap Improvement Minor improvement to code
Projects
None yet
Development

No branches or pull requests

4 participants