New landing page to test marketing copy

[ericholscher]

• Run pelican in poetry
• Add a basic skeleton of a Sphinx landing page.

Preview

https://read-the-docs-site-community--152.com.readthedocs.build/landing/sphinx/

---

📚 Documentation preview 📚: https://read-the-docs-site-community--152.com.readthedocs.build/en/152/

[humitos]

I did an initial review to start having a conversation here 😄

I'm not 100% sold on this but I still don't have enough feedback about how it could be better 😃 . I feel it does not have enough power communicating how good Read the Docs is yet. However, I think we will get there once we start working more often on these pages.

As it is, is already a really good first step. Let's move forward!

[agjohnson]

This is looking like a great start! There are a few points of polish that are needed, but nothing feels too far off.

Images and some content pieces could use some polish, but also feel free to hand these off to me if it's feeling fiddly. This seems like an easy place to be collaborating.

At the top level, this page feels like it needs more positioning or purpose. I suppose we didn't define exactly who we're targeting with this page -- folks that don't know about Sphinx, folks that know about Sphinx but not Read the Docs, folks that think Read the Docs only supports Sphinx? It seems this content is most focused on folks familiar with Sphinx but don't yet trust Read the Docs -- that is, the focus is on building rapport using metrics/testimonials.

I'd say we have the need for a much broader focus to this page, as rapport already feels like one of our stronger connections to users. This content focus can be built up over time, and we can certainly start this page with just users that are familiar with Sphinx already.

But, for this page to be useful for a reader familiar with Sphinx, we should probably answer more reader questions around what value RTD provides and why our approach benefits their Sphinx project. I feel like I'd still have questions if I read this page and didn't know what role RTD plays for my Sphinx project.

[ericholscher]

Pushed a big update to this page that I think works well. Should be ready for another round of review, then we can go live and try it out!

[humitos]

It was really good to work together with Eric on this. I think we did really good progress by pairing on this landing page, set expectations and work on the content plus some new widgets. This is pretty close to be shipped. I will do a final review in the following days.

These are some notes that took in our pairing session:

• Fonts on Mac are weird and we are not sure why
• Main image is not perfect. We talked about using a GIF with hoverxref and livesearch, but I'm not sure how to do that in a way that works and it doesn't look terrible 😄
• We need to add the final images for projects in the "Case study" section

[humitos]

BTW, @agjohnson I resolved some of your review comments already. Feel free to do another round of review on this work when you have time.

[humitos]

I updated this page with the logos we want. With that, this is ready to be shipped. There is a small CSS tweak that it's missing, tho. Keep reading...

I applied these CSS changes to make it look as I want --I don't know how to make them properly, tho.

.ui.cards > .card > .image, .ui.card > .image {
  /* background: rgba(0, 0, 0, 0.05); */
  min-height: 125px;
}

.ui.small.images .image, .ui.small.images img, .ui.small.images svg, .ui.small.image {
  /* width: 150px; */
  width: 300px;
}

They look like this with these changes applied:

I also want to center the logos vertically; but now sure how. cc @agjohnson

[ericholscher]

Yea, I'm also 👍 shipping this and testing it once CI passes. I think super long review cycles are not good for iteration on marketing content, so I think we can definitely move forward with this, and ship an iteration with feedback.

[agjohnson]

I'm going to have to come back to this anyways, I'd prefer to review this before merge. It's on my list for this afternoon, I wasn't able to get to any site work on my friday.

[agjohnson]

Overall, this is a good start, but it still feels like it lacks direction a bit. This would be a page to really flex our muscles on product features, as Sphinx users will get us the most out of any class of user. Speaking more to power user features would be very wise on this page. I'd say we have more work here to make this page convincing or informative to readers familiar with Sphinx though.

I think the direction towards showing features and how they work helps the most here, and would be my vote for continuing work on this page in the future.

Also, the code example is a great addition to this page and could be more prominent. That is the clearest proof of how easy it is to get started with Read the Docs. The work we have on this page next hammering home "what does Read the Docs do?".

[agjohnson]

This header doesn't match the content below. This header sounds fairly vague and generic, but it's also saying "Read the Docs provides all the services you need to host your documentation in one place". The content doesn't agree with this, and is instead "how to host your Sphinx project on Read the Docs".

No strong preference here, but same energy but more specific benefit:

Suggested change

	Everything you need, and nothing you don't.
	Upgrade your documentation in minutes

[agjohnson]

Also, the nesting of elements here is wrong. The heading should be outside the grid, and should be at least inside the div.container, and the grid shouldn't need a div.row class.

[agjohnson]

I fixed the HTML structure. I edited the header for now so this doesn't get lost, but not sold on the edit copy.

[agjohnson]

Moved to #152 (comment)

[humitos]

@ericholscher I addressed most of the feedback that Anthony provided. Can you take a look at the missing points? It looks pretty close to get merged and deployed, IMO.

[agjohnson]

Also, reminder to follow up on the failing checks on future PRs, these checks should be actionable. The html validator shows that the structure of this document is a bit broken, with a spurious </section>. I'll remove it.

[agjohnson]

My original feedback is here: #152 (comment)

I fixed the HTML structure, but might want to tweak this more.

[ericholscher]

Yea, I don't love this heading. We were trying to address the idea that we do a lot less than something like GH actions but also more around docs, but that focus is valuable. I think that is still a strong selling point, and "upgrade your docs" doesn't really tell me much.

[agjohnson]

less than something like GH actions but also more around docs, but that focus is valuable

Aye, and that still seems like a worthwhile focus, but for different supporting content. The config file shows how to use RTD, but we haven't explained on this page that our focus is narrower than other services, or that it's a problem using a service that has too broad a focus.

We could/should totally have that content somewhere on our site though, but I'd expect the supporting content to describe why rolling your own solution is a bad idea, or show all the pieces you'd have to glue together to make RTD, etc.

Also, I'm very not tied to the heading I put up. The config example content is describing how easy it is to get benefits from RTD, so could use a heading that matches that sentiment.

[agjohnson]

I pushed up a number of technical fixes for this page, and addressed CI failures to push this forward.

[agjohnson]

I also want to center the logos vertically; but now sure how. cc @agjohnson

@humitos What you probably wanted to do was give all the images a background color and common dimensions. With a transparent background, the card display will look a little funny. I just moved the image into the card .content for now though

I skipped this by moving the content

[ericholscher]

I added a link to this page from the footer so it will end up on Google, but I think we're ready to ship it 🎉

Thanks for the push @agjohnson, I really appreciate it.

[ericholscher]

Yea, I don't love this heading. We were trying to address the idea that we do a lot less than something like GH actions but also more around docs, but that focus is valuable. I think that is still a strong selling point, and "upgrade your docs" doesn't really tell me much.

[agjohnson]

I added a link to this page from the footer so it will end up on Google

I'll eventually want to move that, but it's fine for now. I'm trying to keep the footer fairly minimal, and I'd like to match the application/website footers as much as I can. Seems we probably want some intermediate page(s) to help with navigation and indexing.

[ericholscher]

I added a link to this page from the footer so it will end up on Google

I'll eventually want to move that, but it's fine for now. I'm trying to keep the footer fairly minimal, and I'd like to match the application/website footers as much as I can. Seems we probably want some intermediate page(s) to help with navigation and indexing.

Yea, it's not a great solution, but will work for now. It doesn't make a ton of sense to link internally since it's a "landing page", but we can invent a nav for it in the future.

[humitos]

The page is deployed and available at https://about.readthedocs.com/tools/sphinx/