H-2798: Update developer-facing docs and fix broken links

[vilkinsons]

🌟 What is the purpose of this PR?

Coming soon.

[TimDiekmann]

Looks good to me, thank you! 🎉 🚀

[github-actions]

Benchmark results

@rust/graph-benches – Integrations

scaling_read_entity_complete_one_depth

Function	Value	Mean	Flame graphs
entity_by_id	50 entities	$$1.57 \mathrm{s} \pm 3.66 \mathrm{ms}\left({\color{red}458 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$53.8 \mathrm{ms} \pm 293 \mathrm{μs}\left({\color{gray}0.673 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$22.2 \mathrm{ms} \pm 128 \mathrm{μs}\left({\color{gray}1.11 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	25 entities	$$79.2 \mathrm{ms} \pm 545 \mathrm{μs}\left({\color{gray}3.65 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	5 entities	$$26.7 \mathrm{ms} \pm 312 \mathrm{μs}\left({\color{gray}2.07 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity

Function	Value	Mean	Flame graphs
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2	$$17.6 \mathrm{ms} \pm 213 \mathrm{μs}\left({\color{lightgreen}-6.259 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1	$$18.0 \mathrm{ms} \pm 206 \mathrm{μs}\left({\color{gray}-1.454 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1	$$18.6 \mathrm{ms} \pm 270 \mathrm{μs}\left({\color{gray}4.58 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1	$$18.0 \mathrm{ms} \pm 191 \mathrm{μs}\left({\color{gray}-3.472 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1	$$17.9 \mathrm{ms} \pm 215 \mathrm{μs}\left({\color{red}5.07 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1	$$18.7 \mathrm{ms} \pm 223 \mathrm{μs}\left({\color{red}7.13 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1	$$17.6 \mathrm{ms} \pm 210 \mathrm{μs}\left({\color{gray}-2.539 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1	$$17.7 \mathrm{ms} \pm 218 \mathrm{μs}\left({\color{lightgreen}-12.070 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1	$$18.3 \mathrm{ms} \pm 221 \mathrm{μs}\left({\color{red}7.70 \mathrm{\%}}\right) $$	Flame Graph

representative_read_multiple_entities

Function	Value	Mean	Flame graphs
link_by_source_by_property	depths: DT=255, PT=255, ET=255, E=255	$$2.07 \mathrm{s} \pm 6.34 \mathrm{ms}\left({\color{gray}-0.117 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=2, PT=2, ET=2, E=2	$$1.12 \mathrm{s} \pm 6.36 \mathrm{ms}\left({\color{gray}2.48 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=2, ET=2, E=2	$$1.09 \mathrm{s} \pm 8.29 \mathrm{ms}\left({\color{gray}-0.766 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=0, E=2	$$106 \mathrm{ms} \pm 760 \mathrm{μs}\left({\color{gray}1.25 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=2, E=2	$$443 \mathrm{ms} \pm 2.29 \mathrm{ms}\left({\color{gray}-0.482 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=0, E=0	$$64.7 \mathrm{ms} \pm 527 \mathrm{μs}\left({\color{gray}1.68 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=255, PT=255, ET=255, E=255	$$2.99 \mathrm{s} \pm 15.6 \mathrm{ms}\left({\color{gray}0.799 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=2, PT=2, ET=2, E=2	$$1.03 \mathrm{s} \pm 6.55 \mathrm{ms}\left({\color{gray}0.987 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=2, ET=2, E=2	$$1.02 \mathrm{s} \pm 4.02 \mathrm{ms}\left({\color{gray}-0.734 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=0, E=2	$$44.3 \mathrm{ms} \pm 187 \mathrm{μs}\left({\color{gray}2.54 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=2, E=2	$$374 \mathrm{ms} \pm 1.60 \mathrm{ms}\left({\color{gray}-0.583 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=0, E=0	$$39.9 \mathrm{ms} \pm 227 \mathrm{μs}\left({\color{gray}3.80 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity_type

Function	Value	Mean	Flame graphs
get_entity_type_by_id	Account ID: d4e16033-c281-4cde-aa35-9085bf2e7579	$$1.44 \mathrm{ms} \pm 10.5 \mathrm{μs}\left({\color{gray}1.86 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_linkless

Function	Value	Mean	Flame graphs
entity_by_id	1000 entities	$$3.52 \mathrm{ms} \pm 21.8 \mathrm{μs}\left({\color{lightgreen}-16.865 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	100 entities	$$2.71 \mathrm{ms} \pm 13.8 \mathrm{μs}\left({\color{gray}0.034 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$2.56 \mathrm{ms} \pm 13.2 \mathrm{μs}\left({\color{gray}0.531 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10000 entities	$$14.0 \mathrm{ms} \pm 149 \mathrm{μs}\left({\color{gray}2.53 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$2.55 \mathrm{ms} \pm 16.1 \mathrm{μs}\left({\color{gray}1.08 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_complete_zero_depth

Function	Value	Mean	Flame graphs
entity_by_id	50 entities	$$4.69 \mathrm{ms} \pm 28.8 \mathrm{μs}\left({\color{gray}-0.971 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$2.84 \mathrm{ms} \pm 16.2 \mathrm{μs}\left({\color{gray}4.52 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$2.55 \mathrm{ms} \pm 22.2 \mathrm{μs}\left({\color{gray}1.01 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	25 entities	$$3.30 \mathrm{ms} \pm 24.4 \mathrm{μs}\left({\color{gray}3.16 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	5 entities	$$2.56 \mathrm{ms} \pm 14.6 \mathrm{μs}\left({\color{gray}-0.499 \mathrm{\%}}\right) $$	Flame Graph

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 21.02%. Comparing base (1aeef59) to head (351bf42).
Report is 795 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4538   +/-   ##
=======================================
  Coverage   21.02%   21.02%           
=======================================
  Files         461      461           
  Lines       15301    15301           
  Branches     2284     2284           
=======================================
  Hits         3217     3217           
  Misses      12043    12043           
  Partials       41       41           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.