Design doc: Landing Page User Stories

[nienn]

Design document for the landing page user stories.
The purpose is to gather ideas and open the debate about what needs to be built into the community site home page from the perspective of the end user.

This will help us define our standard users and map specific user needs, which will in turn allow us to better define specific features and goals.

---

Edit based on @ericholscher first comment bellow.

Am I trying to see if the user stories cover all the various things that users might think

I'm sure I didn't yet cover all the user needs here.
Instead I'd love to see this Design doc being used as a platform for brainstorming on those needs — in the format of user stories — for the landing page. It should be a place where anyone can contribute with an informal story, written from the perspective of a user, a developer or other stakeholder, that needs to accomplish some task or goal on the landing page.

User stories do not translate directly into final features. They have the feeling of ideas in a brainstorm and can help us define future features and goals, but are not yet in any formal format.

[ericholscher]

This seems like a good start, but I don't really know how to review this. Am I trying to see if the user stories cover all the various things that users might think, or are we just going over the structure at this stage? I think it will be useful to have an explicit section about what level to review things, so I can make sure to focus correctly.

[ericholscher]

This is a great breakdown of the different audiences 👍

[ericholscher]

Seems this is a tools section?

[nienn]

Yes, I'd say these stories would probably be resolved in a tools section.
However, I'd like to see a tools section broken down in subsections for different user segments.
For example, not all users need a deep understanding of Docutils to be able to create documentation on Read the Docs.
Messages like this around requirements and tools need to be conveyed and easy to understand, so we don't rush away users that are well in our target audience but are just not able to receive information that would have been useful in a timely manner.

[ericholscher]

This is definitely a good one to remember. 👍

[nienn]

Yup! This is exactly one of the main reasons I think the exercise of writing these down is a great one. There are some features that seem so obvious and taken for granted that sometimes we just forget about and loose them along the way.

[nienn]

@ericholscher I edited the initial description so, hopefully, the document objectives are more clear.

[astrojuanlu]

Rendered version: https://docs--8594.org.readthedocs.build/en/8594/development/design/ext-theme/landing-page/user-stories.html

[agjohnson]

This is looking great. Does it help to have more user stories, or more granular user stories? If so, there are a few stories that we might be able to discuss a bit more thoroughly and could distill down the needs of the user a bit more.

It seems this might help at least to highlight some of the pages we'll eventually want on our website, but might be less helpful strictly discussing what we want on our front page.

[agjohnson]

If it helps to get more granular on this, it might be worth considering these two users -- engineer and technical writer -- as separate cases.

However, I suspect we'd rather point these granular cases towards specific landing pages, not try to cover these in our homepage.

We can talk to engineers easier than we can sometimes talk to technical writers. Our service is not unlike tools an engineer is already using, but can be more specialized tooling than other platforms technical writers are commonly using. Even core features like build automation might not be a direct requirement for some techincal writing teams, and we might have to illustrate our documentation workflow a bit more.

[agjohnson]

Also on the theme of granularity, there are two more granular users here: engineers familiar with Sphinx and the Python ecosystem, and users from other language communities.

This is another case where it's more difficult talking to users who aren't familiar with the Python ecosystem.

A user not familiar with the Python ecosystem would need to know if RTD can even work with their project, and perhaps would benefit from seeing a project that already uses RTD.

[agjohnson]

A few of the common questions/issues that we see when discussing RTD with someone in a technical writing role:

• How do we author documentation? Is there an editor?
• Can you use markdown?
• I feel like I've had more requests for hosted doc features from these users as well -- document page rating/feedback, search tuning, site customization/theming

So, from the conversations I've at least had, these users were more likely to be concerned about their documentation as a product -- and the experience of that product. Also, these users were more likely to be concerned about the workflow of their team, and getting contributions from other teams.

[humitos]

@nienn if I understand correctly, most of this work is already done in the https://github.com/readthedocs/site-community/ repository and we should probably close this PR. Is that correct? cc @agjohnson

[nienn]

@humitos
This was part of the initial UX research for the landing page and the work there is mostly done. It's still open because I'd hoped it could work as a place to submit new user needs when they arose, but we've come to the conclusion that it's not the best platform and/or model for that discussion so I'm +1 on closing.