Docs: Changes to main index page (Diátaxis)

[benjaoming]

This PR replaces the currently unmaintained and deviating introduction with one that should:

a) align with the Diatáxis
b) be easier to maintain (compared to the old wall of links)
c) give two types of very very simplified personas a nice experience: new users and existing users
d) work well on mobile views that do NOT show the navigation sidebar (it's hidden in a burger menu)

Reviewers:

• We decided that we want to work with the content and copy here.
• It would be nice with suggestions for the texts and which links are important, not to mention priority.
• I didn't find a way to reuse TOCs or anything of that nature, so I'm pretty sure that there it's not worth trying to become technical here... just accept the potential for content duplication and manual future maintenance and move on :)

Out of scope:

• Using widgets
• Auto-generating content, because we have NOT decided how we can encode and reuse meta-data

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--10186.org.readthedocs.build/en/10186/

• Developer's documentation (dev): https://dev--10186.org.readthedocs.build/en/10186/

[benjaoming]

Status: Still working out the last bits to give a finished impression...

[benjaoming]

The PR diff preview certainly is a good use-case for being able to switch it off with toggle button :)

[benjaoming]

It seems this might be a bit entangled with #10071

A possible approach is to quickly untangle it, but I wanted to start by pretending that the new sections in #10071 are finished :)

@ericholscher It's very okay if you push changes to this PR 👍 no darlings :)

[ericholscher]

🚀 this is way better!

Great PR description 💯.

I pushed a couple commits to add the guide index, but otherwise I think this is a great improvement.

[ericholscher]

Still pretty odd this is at /integrations, and still kind of talks about webhooks too much? Definitely room for breaking this out into a proper explanation, but not in scope for this PR 👍

[benjaoming]

Yes, we need to fix this ASAP. We need a good introduction and overview.

kind of talks about webhooks too much?

That just gave me an idea that we need a graphic instead of a bunch of words there :)

But yeah, #10071 should get us closer

[ericholscher]

😍

[benjaoming]

I really liked seeing that, too, it felt like it opens an arena for more tutorial content

[benjaoming]

When I had this in draft mode, it was because I thought the text was a rough first-pass. Seems there were some rough edges, so gave it some polishing.

It would be nice with a second pair of eyes on the language, but please feel free to merge after that 👍

[benjaoming]

I did have introduction sentences in a draft but decided to remove them again because the page seemed understandable without them. But I'm happy with both :)

[ericholscher]

I think it's useful as a quick intro 👍

[humitos]

I took a really quick look a the files changes and this is way better than what we have now. I'm 💯 on merging this and move forward. We can always come back and improve it as we need. This front page is not perfect, of course, but it gives me a lot more condensed information in an easy way that I can quickly parse. I never liked the "wall of links" we had 😄

[ericholscher]

I agree -- it's a huge improvement. Let's ship it! 🚢

[benjaoming]

Totally agree @humitos - we tried not to get caught it all the possible pit falls of ideas and perfectionism :)

@ericholscher great direct changes 💯 🙏 - I'm gonna take a wild guess here that the PR is OK as it is.

[benjaoming]

Oh you merged it exactly when I was gonna do it 😂