1582479 - Document Glean crash capabilities as a use-case focus

[travis79]

This adds a new example application to the samples directory, and a walkthrough readme to a new section titled "Focused Use Cases" in the docs

[mdboom]

This is great. I like having some narrative documentation that describes the "workflow" of what it's like to use Glean and it's a fun read.

I do worry about the maintenance burden of some of these duplicated instructions (that are likely to change with the Gradle plugin etc...) Maybe we could help by:

1. Adding a build of this project to CI
2. Instrumented tests would be nice, but less critical given the simplicity of the actual functionality, IMHO.
3. Maybe put a date at the top of the chapter so that it has more of the feeling of an article and to flag that it might possibly be out of date (though we'd endeavour to keep it updated...)

[mdboom]

Would it be better to license the example in the public domain? Developers may be disinclined to use it as the basis for production work otherwise... (I know the MPL should be fine... it's more about optics...)

[travis79]

Good question! I just followed suit on what the sample application does in regards to licensing, the only difference is I included the entire license file rather than just the header at the top of the MainActivity.kt

[travis79]

@mdboom I tried to address your concerns as best as possible. The only one I that was a little awkward was adding semantic line breaks, which roughened the formatting of the rendered markup a little bit, but not bad.

Would you be okay with me filing a follow up bug to add an instrumented test and add the build to CI, or would you rather see it added as part of this PR?

[mdboom]

I think filing a follow-up bug is fine. CI additions can become rabbit holes, and it's better to have these docs than not have them :)

[travis79]

I think filing a follow-up bug is fine. CI additions can become rabbit holes, and it's better to have these docs than not have them :)

Bug filed!

[codecov-io]

Codecov Report

Merging #399 into master will increase coverage by <.01%.
The diff coverage is n/a.

@@             Coverage Diff              @@
##             master     #399      +/-   ##
============================================
+ Coverage     76.38%   76.39%   +<.01%     
+ Complexity      308      307       -1     
============================================
  Files            95       95              
  Lines          5362     5360       -2     
  Branches        627      627              
============================================
- Hits           4096     4095       -1     
+ Misses          802      801       -1     
  Partials        464      464

Impacted Files	Coverage Δ	Complexity Δ
...ozilla/telemetry/glean/debug/GleanDebugActivity.kt	76.66% <0%> (+0.9%)	6% <0%> (-1%)	⬇️
...n/java/mozilla/telemetry/glean/rust/LibGleanFFI.kt	66.66% <0%> (+1.96%)	0% <0%> (ø)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0d4cde2...fd7d031. Read the comment docs.

[badboy]

Content-wise this is pretty good!
I have some nits regarding links and so on and in regards to wording.

As this is becoming part of the official Glean SDK book I think it should match the other documentation a bit in style (e.g. not referring to "I" and "my personal experience").
Plus some cross-linking to existing docs could help.

First I also thought about whether we need that whole project files (gradlew, .gitignore, etc), but I guess that keeps it separate enough so people can copy just that project out and build it independently, so I'm not gonna complain about that.

[travis79]

Okay, I've taken a step back and refactored this to be much more in-line with the tone of the rest of the Glean docs.

Most notably, I removed the example application completely as it was just going to be a maintenance issue and didn't really serve the use-case documentation that much anyway.

I'll save the friendly "narrative" style and full example application for the blog post, and I will host it from my own GitHub repo so that it can age with the blog post and not affect the Glean repo here.

[Dexterp37]

What do you mean here? Can you please expand on what's missing?

[travis79]

I added the same link to the probe_scraper docs as found in the "Adding Glean to your project" section, which should cover the "next steps" required.

[badboy]

Minor nits, but I think this tone is much more fitting now!
I encourage you to post the original version as a blog post though.