Mobile: Missing READMEs for Some Mobile Components

[SiobhyB]

As part of a discussion with @enejb around https://github.com/WordPress/gutenberg/pull/29670, it came up that some mobile components are missing READMEs. This can be seen by browsing through a few different folders in the components/src/mobile folder: https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/mobile

In our discussion, we agreed that READMEs are a good way to communicate a component's purpose, encourage re-use, and help developers, especially those new to the project, to gain familiarity with its usage. This is something I can appreciate especially, as someone not only new to the project but to development in general.

It was suggested I create this separate issue for a wider discussion around ways to encourage the creation of READMEs with new components as well as possibilities for tackling the current situation.

Looking forward to hearing any thoughts! 🙇‍♀️

---

Edited: Following the discussion in the comments of this issue and the example shown set in this ticket, I've gone ahead to compile the following list of mobile components that are currently lacking a README:

• [ ] audio-player
• [ ] bottom-sheet
• [ ] clipboard
• [ ] color-settings
• [ ] focal-point-settings-panel
• [ ] global-styles-context
• [ ] gradient
• [ ] gridicons
• [ ] html-text-input
• [ ] image
• [ ] keyboard-avoiding-view
• [ ] keyboard-aware-flat-list
• [ ] layout-animation
• [ ] link-picker
• [ ] link-settings
• [ ] media-edit
• [ ] picker
• [ ] readable-content-view
• [ ] segmented-control
• [ ] utils

[hypest]

Interesting idea! Sounds like it can be useful to document components, although I'm not sure what exactly to document and how to keep the documentation healthy and up-to-date.

@enejb , can you perhaps share an example?

Also, not sure, is this a practice used in Gutenberg-web as well? I think I'm not seeing the individual components be documented via READMEs, right? And if not in Gutenberg-web yet, then this ticket might not be strictly mobile related, right?

[SiobhyB]

An example of a README that helped me a lot is for the BottomSheetSubSheet component, I feel like it saved me a bunch of time. :) https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/mobile/bottom-sheet/sub-sheet

I think I'm not seeing the individual components be documented via READMEs, right? And if not in Gutenberg-web yet, then this ticket might not be strictly mobile related, right?

This question prompted me to search to see if there was an open issue for the web, as I also see a few missing READMEs there. A search for label:"[Type] Documentation" README is:open indicates that there are open issues for some of those components missing one and there's also this issue to keep track of all components missing READMEs under the Block Editor folder: https://github.com/WordPress/gutenberg/issues/22891

So, definitely doesn't seem to be strictly mobile related, but it does seem there's already a movement towards adding more READMEs on the web side.

Maybe listing out the mobile components with missing READMEs, like in #22891, would be a good starting point? I'd be happy to do that if you think it might be a good idea!

[hypest]

Maybe listing out the mobile components with missing READMEs, like in #22891, would be a good starting point? I'd be happy to do that if you think it might be a good idea!

Thanks for the extra context Siobhan! Yeah, piggybacking on that ticket would be my recommendation, thanks!