Re: [Bloom] review starts on 13th of May

From: Joaquin M López Muñoz (joaquinlopezmunoz_at_[hidden])
Date: 2025-05-20 16:25:09

El 19/05/2025 a las 22:36, Peter Turcan via Boost escribió:
> Joaquin - thanks for your comments on my comments, here are my comments on
> your comments on my comments:
>
>> In which ways do you think that this primer does not fulfill the goals of
> your proposed "Introduction" section?
>
> My issue with your Primer is that it explains what a Bloom filter is, not
> what it does - start the *Introduction *by answering the question "what is
> the problem that a Bloom Filter solves?". Don't move onto the "is" until
> you have answered "why should I be interested in this?".
>
> A Bloom filter *is* a probabilistic data structure where inserted elements
> can be looked up with 100% accuracy, whereas looking up for a non-inserted
> element may fail with some probability called the filter’s *false positive
> rate* or FPR. The tradeoff here is that Bloom filters occupy much less
> space than traditional non-probabilistic containers (typically, around 8-20
> bits per element) for an acceptably low FPR. The greater the filter’s
> *capacity* (its size in bits), the lower the resulting FPR.
>
> My 2c is that an *Introduction *section should describe the purpose and use
> cases of a library that is understandable to a program manager or analyst
> who is researching the libraries to consider for their project but who will
> not be as technical as their developers. It is people who need assistance
> that turn to overview documentation - typically experts in the field go
> straight to the *Reference*.

Makes sense.

> If fraud detection is not the main use of Bloom Filters, what is? Be bold
> and articulate use cases. Every use-case you mention will pull in users.

Some use cases (rather, areas of application) are mentioned in the primer.
I can try to make this more prominent.

>> Have you written this proposed introduction based on your reading of my
> docs or from some other sources?
>
> Other sources, for the reason described above.
>
>> I can try to organize the tutorial as part of a narrative where a full
> example is built. I have some problems though with that, as some parts,
> notably the
> one where I describe the different configuration options, don't look to me
> amenable to that approach.
>
> Configuration options belong in the *Getting Started/Installation*
> sections, a *Tutorial *should step by step. Consider deciding on the
> appropriate configuration for your tutorial, and run with that. The purpose
> of a first tutorial is to provide the user with a "feel good" experience
> that encourages them to go further - it need not be complete in any sense.

Well, not sure filter configuration belings in the getting started section,
but I'll see what I can do.

>> Do you have any favorite Boost lib referencewise?
> Take a look at this ref entry from Boost.Geometry - I don't have to look
> out of this page to understand what it does, and how to use it:
>
> https://www.boost.org/doc/libs/1_85_0/libs/geometry/doc/html/geometry/reference/algorithms/intersection/intersection_3.html

This makes sense for the kind of entities described in Boost.Geometry,
namely meaty algorithms with a lot of explaining behind. Most of the
entities described in Boost.Bloom are far simpler than that, and far
less isolated. For instance, boost::bloom::filter has 18 constructors,
what would I write about them other than list them and say what they
do in one line?

The only important component in the library is boost::bloom::filter.
I tried to give the more user-friendly explanation, examples etc. in the
tutorial --what's left in the reference is just dry exposition, standard-
style. I still feel this is ok as long a the tutorial does the heavy work
of introducing the users to the component more gently.

> Users of your library will jump straight into *Reference *pages, and
> straight back out again. Best to fully describe the purpose and
> functionality of each construct without requiring leaving that page.
> Repetition within a *Reference *is not necessarily much of an issue as they
> are not read front to back like a book.
>
> Perhaps identify the reference entries that do the heavy-lifting, and
> consider expanding them so that they are self-contained explanations with
> examples and diagrams if needed.
>
> Hope this is useful and good luck with this effort!

It is useful, thanks for your feedback. I'll see to best applying it
to improve the documentation.

Joaquin M Lopez Munoz