mozilla / taar-lite

A lightweight version of the TAAR service intended for specific deployments with reduced feature visibility.
Mozilla Public License 2.0
2 stars 6 forks source link

Docs on the GUID-GUID recommender #45

Closed dzeber closed 5 years ago

dzeber commented 6 years ago

Adding some doc on the logic underlying the GUID-GUID recommender, treatments, graph representation etc.

I've created two doc pages:

There is also some minor cleanup of the main README.

r? @mlopatka @birdsarah

dzeber commented 5 years ago

@birdsarah Thanks for taking the time to review this in depth - I appreciate the detailed comments, and I think they've really helped me hone down the focus.

I've made the requested changes to GuidGiudRecommender.md--updates to the other doc will follow.

I've also added a few details to the README about the taar_lite_guidguid.py processing. One thing I wanted to call out is that I didn't see any pruning of rare combinations in there (I think we'll be doing this as a recommender treatment instead), so I removed that bullet point.

dzeber commented 5 years ago

@birdsarah @mlopatka @crankycoder Thanks everyone for the detailed review! I believe I've addressed every comment, either through changes or by replying.

In response to Sarah's overall requests:

  1. obsessively consistent use of terms, and ideally a definitions section. This is to help people like me who are new and really don't know whether words are interchangeable and so it reduces the cognitive load.

AFAICT I've used terminology consistently throughout, and relevant terms are now all defined (and usually bolded). Definitions are often inline in the text as opposed to in a formal glossary.

  1. Mini examples for each of the treatments for people like me who are more concrete / visual thinkers

I've added an example for each treatment, some with graph diagrams. ASCII art FTW! I'd love to find a better way to create diagrams, but ideally it would render nicely in Github markdown without relying on external tools.

  1. Do not mix-in production / deployment details. They can be written up in a seperate doc about app/production.

Done - these have been removed and parked for future use.