Rework onboarding and template repository?

[astrojuanlu]

When I started working on #8329, which describes our upcoming new tutorial for Read the Docs along with the corresponding design document, I realized a few annoyances of our onboarding process.

At the moment, the user is greeted by this text right after they set up their account:

However, there are a couple of problems:

• The first link takes the user to https://docs.readthedocs.io/page/intro/getting-started-with-sphinx.html - for the completely uninitiated, it is not at all clear how to proceed from there (I validated this with a real user some months ago).
• The second link is more friendly, since it doesn't require the user to touch the command line at all. However, it manually imports https://github.com/readthedocs/template, a really old template of ours, and after the first build is successful, it is impossible to continue adding content. This might explain why we have a bunch of pull requests piling up here https://github.com/readthedocs/template/pulls

I think the one-click demo is awesome, but not being able to add more content can be a bit frustrating. And our Sphinx guide might not be that helpful.

A more flexible alternative would be to direct folks to https://github.com/readthedocs/template/generate instead, which forks the template on their GitHub account, and then tell them to import that project into RTD. This has some pros and cons:

• Pros: allows users to continue modifying content, we encourage connected repositories.
• Cons: assumes GitHub, no more 1-click demo (unless forking template + importing it is technically feasible with enough permissions)

We can discuss this in the context of long term vision (how do we want the onboarding to be, how does this fit with the beta UI, etc), and in the context of the tutorial I'm about to start writing (what do you want me to write in the first section of the tutorial, do we need a new template for this, etc), since I left it somewhat underspecified:

Fork a starter GitHub repository (something like our demo template, as a starting point that helps mimicking the sphinx-quickstart or cookiecutter step without having to checkout the code locally)

Thoughts?

[ericholscher]

I'm 👍 on revamping our onboarding. There's a lot of technical debt there, and I'd love to have the tutorial allow us to work on improving it. Definitely forking a tutorial repo is going to be much better to show features (eg. pull requests, edits, etc.), so that seems like a good step forward, and could be written into the tutorial.

We should also have the template repo show off way more of the features. So something like autodoc, some kind of search demo, etc.

[nienn]

As a completely uninitiated, when I first started this process and got thrown into the getting-started-with-sphinx page, what I most missed was a brief introduction, without going into too much technical detail, about what is Read the Docs App, what problems is it trying to solve, what are it's dependencies and a clear, very much simplified, path that I would need to follow in order to get from where I was to having a complete working documentation project.

Another difficulty I've found was having too many in-text hyperlinks. In some places the text even relies on knowledge of the text on these links to make sense. In other places it links just to a few paragraphs bellow. While this is great for an advance user, an uninitiated user needs to have a path more clearly delimited.

I ended up having too many windows open that I intended to read at some point and getting quite lost on priorities and relevance.

Edit: There is some good information here — phinx-and-rtd-for-writers — that could be worked into a more generic intro and placed upfront.

[ericholscher]

Edit: There is some good information here — phinx-and-rtd-for-writers — that could be worked into a more generic intro and placed upfront.

I'm happy to have that content re-used. Perhaps as a high-level "What is Read the Docs" page in the docs?

[astrojuanlu]

That could be the "The Read the Docs way" chapter we proposed in the tutorial, but we put it on its own page instead?

[ericholscher]

That could be the "The Read the Docs way" chapter we proposed in the tutorial, but we put it on its own page instead?

Perhaps. I see them a bit differently. One is a topical guide that's basically "what is this ecosystem of tools?". The other is "Here is our opinionated recommendation for how to manage your docs".

[astrojuanlu]

This was addressed in #8504, closing!