"How Dat Works" is missing from the documentation
anarcat opened this issue · comments
A critical piece of documentation, How Dat Works is missing from the documentation site. The how-dat-works URL gives me a 404.
I suspect this is because the item is not linked in the menu but i'm not familiar enough with Minidocs to fix this myself.
@joehand removed the link to this section in commit d1399d3 on 2017-05-31.
I think there was concern that the current version of "How it works" got outdated and made some inaccurate claims (eg, about de-duplication), and it made more sense to direct people to the specs or a (future) blog-post overview. Having documents of different lengths is really useful for ramping up to familiarity with the project, but hard to keep accurate and up-to-date. The whitepaper is another coherent resource that has been de-emphasized because it's out of date.
But maybe i'm putting words in Joe's mouth?
well, it would sure be useful to have at least one document that would clearly explain the inner workings in a single place. now we're left with many outdated documents instead of a single working one. :)
even adding a warning on top of that page would have been better than just orphaning it, in my opinion, because it's still shipped in the source and researchers like me might be led to believe it is still valid and accurate...