Guides

[fortmarek]

@naqvitalha has mentioned an idea to create step-by-step guides for how to use components.

We could for example create a tutorial for how to create our Twitter example from scratch.

Personally, I think step-by-step tutorials are not the easiest thing to maintain (if you make a change in the first step, you might need to change all the subsequent steps, too), so I'd be for it only if there's a good case for it.

I'd rather create some specific examples showcasing FlashList-specific props (those which are not part of FlatList).

Thoughts? 🤔

[naqvitalha]

I think we should have at least 4 guides:

1. A very simple one where we explain how similar it is to FlatList and explain estimatedItemSize and why it's needed. But someone not familiar with FlatList should also get something out of it. This can also include pagination.
2. An advanced one where we can explain different types of items and how to handle them
3. A doc to explain how to write performant recycling friendly component and link this in 1 and 2.
4. Ever since the benchmark how I approach profiling has completely changed and it's an amazing new way to test performance. There should be a guide explaining that too.

One more thing is the main read me. It's extremely barebones right now and you don't really understand anything about the list from it. Also, some of our samples like pagination don't seem self explanatory, they're more like tests.

I strongly feel that we need to relook at this as a whole. Our familiarity can make us biased.

[fortmarek]

I think we should have at least 4 guides:

I agree with the list - I misunderstood your notion of guides as I thought it would be more of a tutorial. What you have listed here is more-or-less presenting a sample and explain on it trickier things about the list which is imho a good approach 👍

Ever since the benchmark how I approach profiling has completely changed and it's an amazing new way to test performance. There should be a guide explaining that too.

Absolutely - I think it should be included with this PR.

One more thing is the main read me. It's extremely barebones right now and you don't really understand anything about the list from it.

True, although I don't think we should add too much there. We'll have the landing page and a documentation microsite - we should make sure to link to them. Apart from that, maybe adding some quick sample, image, or gif to communicate the core idea of what the component is about.

Also, some of our samples like pagination don't seem self explanatory, they're more like tests.

I think that's ok as long as we include samples in the documentation itself instead.

[davebcn87]

I agree with the list that you wrote down @naqvitalha!
Maybe that's for a next iteration, but I'd like a guide on how measure TTI, Blanks and FPS. I'm not still 100% sure the steps we need to do to profile this metrics.

I agree about the readme, even if we copy-paste the basic example guide I think we should make it more attractive (at least for the open source milestone).