MaikuB
[flutter_local_notifications] Refactor the README into platform-specific guides
Based on the work in #2308, this PR will split the README into platform-specific guides and topics (that can then be hosted on another website besides github, if desired), and leave the main README for Dart-specific details. Specifically, my goal is to:
- split the main README into different markdown files, at least one per platform
- reorganize the contents on each page (eg, group all Gradle changes together)
- rewrite the docs for clarity
- include more links and examples
- remove info that only applies to versions of Flutter or platforms this plugin no longer supports
Progress:
- [x] Android setup guide
- [x] iOS setup guide
- [x] Windows setup guide
- [x] General usage guide
- [x] Android usage guide
- [x] Darwin usage guide
- [x] Windows usage guide
- [x] Linux usage guide
- [x] Main README cleanup (should only have: links to all other guides, feature matrix)
Verifying that all the new docs are correct (by going through them with a brand new app) is on my list but will take a bit longer. In the meantime, I've reviewed, revised, and re-reviewed all of these several times, and caught mistakes in the README and API docs, so I'm reasonably confident.
cc @davetrollope if you're interested
Closes #2196 Closes #2308
Just finished the Android page, I will try to use a similar style for the other platforms.
Sorry for the slow reply - busy month. I will take a look @Levi-Lesches
@MaikuB The branch is at the halfway point: It has the setup guides for all three platforms that require it (android, iOS, and Windows) that explains all the compile-time steps and platform code changes needed to get their apps compiling. I also finished the cross-platform usage guide, which describes at a high level how the plugin is used and all the common features between the platforms (basically, all the methods on FlutterLocalNotificationsPlugin.
Now all that's left is to make a platform-specific usage guide for all the platforms (android, darwin, linux, windows, and web), with details on all the initialization settings, permissions nuances, and notification details. These are mentioned throughout the docs I wrote, so it's important I get them ready soon, but this is also a good time to start a review if you want to since the docs that are pushed are complete thorough.
Once I've finished all the other guides, I'll rewrite the main README to be shorter and more to-the-point, with a table of links to the other setup guides.
Also, can you confirm that MacOS and Linux don't have any special build / platform folder setup, like AppDelegate.swift on iOS or build.gradle on Android?
@MaikuB Ready for a review! Check out https://github.com/Levi-Lesches/flutter_local_notifications/tree/readme-refactor/flutter_local_notifications and all the links in the table there (1,300 lines of docs...)
The tests can probably be fixed by just running them again. I made a PR to fix the windows tests at #2696
A lot of paragraphs are being repeated in each of the platform-specific usage guides. There a way to reduce the repetition? One of the goals was to help the docs easier to digest but the repetition can add more "noise" for readers to sift through as they go through each platform
A quick note on this, I tried to balance the repetitiveness against the idea that each of these guides can be standalone. There's a lot of setup and configuration for each platform, so imagine a dev trying to configure their app across all major platforms. The intended flow is to first read the general usage guide, then, for each platform they intend to support, the platform-specific setup and usage guides.
Someone who is setting up all the platforms might have spent days in between reading the general usage guide and the Windows-specific usage guide, so I tried to include enough in each document so that the reader can orient themselves without referring to anything else, but if they want more details, they might need to click a link. So that results in some introductory sentences being repeated, but any code examples, external references, and in-depth explanations should only be in one place. I'll give another read-through to make that more consistent.
I'll also get around to tapped vs pressed vs clicked, I think I'll try to stick with pressed because of the desktop options. It's a tricky problem because, as with Flutter itself, I was writing the Android and iOS docs first and then you find yourself using mobile-first terminology 😓
There's a lot of docs, so I do think there's some value in merging sooner and making finishing touches later. There are a number of GitHub issues that pop up regularly and new users who need to set up that could really benefit from these. I personally have set up a few projects with notifications since starting this PR and have exclusively used these to breeze through everything, and I want others to benefit from that.
A quick note on this, I tried to balance the repetitiveness against the idea that each of these guides can be standalone. There's a lot of setup and configuration for each platform, so imagine a dev trying to configure their app across all major platforms. The intended flow is to first read the general usage guide, then, for each platform they intend to support, the platform-specific setup and usage guides.
Someone who is setting up all the platforms might have spent days in between reading the general usage guide and the Windows-specific usage guide, so I tried to include enough in each document so that the reader can orient themselves without referring to anything else, but if they want more details, they might need to click a link. So that results in some introductory sentences being repeated, but any code examples, external references, and in-depth explanations should only be in one place. I'll give another read-through to make that more consistent.
These are a fair points and understand that now so can disregard my point on that. Can see how it goes based on feedback later on
I'll also get around to tapped vs pressed vs clicked, I think I'll try to stick with pressed because of the desktop options. It's a tricky problem because, as with Flutter itself, I was writing the Android and iOS docs first and then you find yourself using mobile-first terminology 😓
"Pressed" makes sense to me and as it's agnostic. It's also used by the Flutter team e.g. onPressed
There's a lot of docs, so I do think there's some value in merging sooner and making finishing touches later.
Sure. Let me know how you go with the feedback I left behind. I saw your mention elsewhere on health issues and hope you're getting better. Besides that, open-source work is typically done by those donating their spare time. If there's bits I can help then let me know and I'll see when I can make those adjustments directly to your fork. I'll also do some changes once PR is merged e.g. see if this can be used based on your changes, which had been mentioned before
