DISCOVERY-335: Setup IndexPage for docs

[azinit]

Background

Changelog

Setup IndexPage docs with simplifying "OVerview" article

https://www.gatsbyjs.com/docs/

[netlify]

✅ Deploy Preview for pr-sliced ready!

Name	Link
🔨 Latest commit	a085802
🔍 Latest deploy log	https://app.netlify.com/sites/pr-sliced/deploys/632829db2572570009e32ade
😎 Deploy Preview	https://deploy-preview-525--pr-sliced.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[illright]

Okay, here goes.

1. The actual textual content is too far down the website.

Here's my flow to start learning about FSD with this docs setup (excuse the slightly sarcastic language, I'm imitating a busy user):

1. Click Get Started on the landing page
2. Read the introduction paragraph
3. Look through the cards on the index page (they're pretty big, on my 14" laptop I need to scroll a lot to get an overview)
4. Click Get Started (again? I though I was already getting started)
5. Read another introduction paragraph (again? give me the content already)
6. Look through the cards:

• "overview", finally;
• "quick start", after two clicks on "get started"? rrrrrrrrrrrr;
• "decomposition cheatsheet", will probably refer to it later, don't need it for now

7. Click "overview"
8. Aha, readable text!

Yeah, I think it's a bit too hidden away for being so essential. Here's the Gatsby flow, and why they're successful in their structure, in my opinion:

1. Spend literal ages finding the link to the documentation from their godforsaken landing page (for heaven's sake Gatsby do something about your fricking landing page)
2. Read the introduction paragraph
3. Click on a colorful and inviting card that's prompting to start
4. Aha, readable text!

So, what they got right is:

• their card is super cute and inviting
• the cards are horizontal ⇒ you see all the options right in front of you, no need to scroll even on a laptop
• the card that gets you started actually gets you started instead of leading to another index page

2. The edits to the content of the intro make it harder to comprehend (to me personally)

Also, FSD have few core-concepts:

This section, I remember it from the original intro page (and remember removing it). What I don't like about it is the imparallelism of the options listed there:

• Public API — that's a visible attribute of an FSD project, represented by actual files (index.ts)
• Isolation — that's an invisible concept that is more of a defining principle for why things are the way they are in the methodology
• Domain Driven — that's a property of FSD, syntactically an adjective (as opposed to isolation, which is syntactically a subject)

So hopefully you can see where I'm going with this — this list feels a bit haphazard in its content, which confuses me as a reader as to what exactly it's trying to tell me. And links, the links are back, nooooooo :D

└── src/

This huge file system tree thing is nice, but not very suitable for the introduction, imo. The introduction is meant to hammer the following things into the mind of a reader:

• FSD is a frontend methodology and it's useful to me because I'm a frontend developer in a team
• FSD is telling us how and where to put files (the particulars of this don't matter quite yet)
• The three knights of FSD are layers, slices and segments
• I can tell these things to my teamlead to make them adopt the methodology
• I can take these steps to adopt FSD incrementally

This filesystem feels like too much details, so I think we'd better wait with it. Also I think it'd be really nice as an interactive widget, not just a code block, but that's 💄 for the future.

See also

This is kind of a crossroads for the reader. After reading the intro (till the end), they are slightly interested in the methodology, so now they want to learn the particulars. I think it's best at this stage to lead them by the hand to the next page exactly instead of confronting them with a choice.

3. When the very first thing in the docs starts with a caution, I'm immediately worried

We have this prominent caution block at the very start of the overview page. Me as a reader, I'm used to seeing such things in alpha-stage products, and that caution is usually telling me to expect bugs and be careful in production. We, however, don't really need our users to watch out for anything, and in my opinion it's expected that you won't understand everything about the methodology by simply reading one page out of many that there are. So I'm not sure what this warning is trying to achieve, but it instills anxiety in me as a reader.

4. [minor] Not a fan of those bright blue rectangles around the terms

They are too bright, they hurt my eyes a bit. And also I'm not quite sure why we need to highlight these terms so prominently, they are important, but they're not that important.

---

Now here's my list of suggestions:

1. Style the cards in the index page differently. Make them fun and colorful, like in Gatsby, arrange them in a grid and cut down the amount. 2 cards is the ideal amount, honestly :)
2. Roll back the edits to the intro. Yeah, I'm definitely saying this because I wrote the previous version, but I truly believe we had it quite nicely already, I don't really see a reason to change it