flutter_local_notifications icon indicating copy to clipboard operation
flutter_local_notifications copied to clipboard

[flutter_local_notifications] Reorganize the readme in to smaller digestible blocks

Open davetrollope opened this issue 1 year ago • 8 comments

When I tried to adopt the flutter_local_notifications package, I found it difficult to work through the readme. This PR proposes isolating the larger platform specific blocks in to separate files making the overall readme easier to follow.

I have updated to include the latest 17.1.0 updates to the README.

davetrollope avatar Apr 21 '24 18:04 davetrollope

Thanks for the PR. I understand the reason behind the changes and for it but will take me some time to digest to see how the changes work. Do you by chance know how this will work on pub.dev and if there similar examples on pub.dev? Mentioning it as a readme will show up on the readme section and I don't know what would happen if a user was to click on, say, the link to the Android markdown file

MaikuB avatar May 01 '24 09:05 MaikuB

I am not sure about pub.dev, but I think it follows standard markdown. I will investigate and see if I can find some examples to verify.

davetrollope avatar May 01 '24 13:05 davetrollope

After doing some research, it looks like relative links are expected to be rewritten to github URLs. That means following the links would hop to the github view of the page, e.g. https://github.com/MaikuB/flutter_local_notifications/blob/49dc49d7ab19ceb6afcf99bfb84d5807c515aaf7/flutter_local_notifications/Android.md

I'm in two minds about this.

  1. It might be a bit disconcerting to be forced over to github for subsections, and then have to hit back or close the tab to continue the overall flow of setup - at least as the subpages are written right now. Perhaps some nuanced updates recognizing this would make it intuitive.
  2. perhaps keeping everything in one readme is better, but maybe we should reorganize the file in to complete sections/walkthroughs for a platform (perhaps with a badge that identifies common setup?

Open to thoughts and ideas.

davetrollope avatar May 06 '24 03:05 davetrollope

Thanks for investigating. I agree that it's disconcerting to be taken elsewhere whilst in the middle of reading instructions. I remembered a while back I was notified about https://docs.page/ where following a convention using that domain allows content to be pulled from repo (reference https://invertase.io/blog/introducing-docs-page). Perhaps this an opportunity create the docs folder and move the content of the readme that has been split there and change the readme to have a link that says go to docs.page/MaikuB/flutter_local_notifications for more info for more details on how to use the plugin?

MaikuB avatar May 09 '24 09:05 MaikuB

Yes, I like the idea of that. I will start playing with it.

davetrollope avatar May 09 '24 15:05 davetrollope

I second the idea of a smaller main README linking to other pages with more details. Lets readers understand the bigger picture faster while still getting to choose when to zoom in on a specific platform, function, etc.

Levi-Lesches avatar Jul 16 '24 04:07 Levi-Lesches