Hi people, Thank you so much for your feedback!
The new animations are plain cool.
Thank you Matt. The animation framework is python based, called manim: https://www.manim.community/ and was developed by Grant Sanderson for 3Blue1Brown, one of my favorite math channel: https://www.youtube.com/watch?v=l6DKRf-fAAM . It's very useful to illustrate dynamic graph algorithms. Since the final animation matters more than its underlying python code, I had little scruples generating the python scaffolding with AI, although automatic generation can only get you so far because it has little to no pedagogical/spatial/temporal/esthetic awareness. I keep a library of small scenes that I can reuse across meetups, docs and conferences: https://github.com/Becheler/animations
I would totally recommend continuing down this path.
Noted. Full steam ahead then!
Yes, the new docs are a million times better [...] ship it.
Thank you Christian! Your feedback matters a lot! The ship has sailed !
Absolutely yes! Thank you so much for doing this! It is already way more user friendly and accessible.
Thank you Andrzej, you're welcome! This was a group effort, we can thank the Alliance for the support, Joaquin and Jeremy for their regular advice, contributors and workshop's attendees (Andrea Cassioli, Sylvain Ducomman and others) for useful feedback :)
For instance, I do not see a Reference section
This is a painful WIP. There is a Bibliography page in About > Bibliography (see https://491.graph.prtest3.cppalliance.org/graph/about/bibliography.html ). I just ported the old pattern to the new antora system: one central Bibliography with bibtex-generated references that reference a handful of algorithms (coverage: ~47/108). I am still debating about to make this system less susceptible to rot. References are algorithm-specific: contributors should not have to touch high-level pages when documenting a new specific algorithm contribution. Similarly, a user exploring the high-level documentation doesn't care about the total list of papers, they just want to know which paper was used to implement a given algorithm. So from both ends the reference should be localized on the algorithm page, not library-wide. It is also more self-sustainable, as a Reference section can easily be documented as mandatory in a contribution template. This seems to be the approach adopted by NetworkX, the python graph library. Two things we lack are 1) How to Cite and 2) BGL general references (Lumsdaine these, BGL book etc). Not sure yet where and how to include them. Feedback welcome :)
For instance, I do not see a Reference section
Oopsie I just understand now you mean a flat list of symbols ? Two things worth noting. The page itself is titled with the code spelling (`predecessor_recorder`), it's only the left-nav label that is prose ("Predecessor Recorder"). And the search bar is meant to cover exactly this case: typing `predecessor_recorder` takes you straight to the page, since the identifier is indexed from the heading and body. On bringing back the old flat symbol table (table_of_contents.html): it was actually highly incomplete and it's mixing purposed (flat symbols refs + conceptual navigation), so I'd rather not reinstate it as-is, the search box is the better lookup-by-symbol path going forward. It is also much easier and robust to maintain (new contributors should not have to touch high-level pages to document algorithm-specific symbols). If you ever search a symbol and it doesn't surface, just ping me, that's a much more useful signal than the old list. Long-term I would love to have an automated extraction of such symbols (mrdocs to the rescue), that would solve your question and my worries. Again, feedback welcome.
In the front page, it is not immediately clear that the cool animation actually illustrates what the following code snippet does.
Noted, I will make this more explicit.
In fact, the animation moves so quickly that I do not know what is actually being illustrated. (It is still cool though.)
Noted, I will expand the timing. I was trying to keep the animations under 15 seconds to match the ever-shrinking attention window of my generation and those who follow. Worth reconsidering.
Please do not use `using namespace boost` and instead prefix every function call with `boost::`
Agreeed.
Rename distances/predecessors to distance_storage/predecessor_storage. Then rename dmap/pmap to distance/predecessor.
Beautiful. I will rework the landing page code + animation and keep you updated :) Thanks again people ! Arnaud