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/refere...
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