Too much documentation!

[glennsl]

Hi! Great job on the documentation! There's only one problem: There's too much of it! At least on the front page (i.e. the README). Redex includes the readme in the record that is indexed for search. The consequence of it being too big is that Algolia refuses to index it, and so this package isn't discoverable through search! Which is unfortunate since we definitely want to promote well-documented packages.

Even if the documentation was shortened to below Algolia's limit (10k bytes total for a record), indexing that much content makes the search less relevant anyway. So... would it be possible to move (the bulk of) the documentation to a separate markdown file, and link to it from the Readme instead? That would solve all my problems at least :)

Thanks!

[stroiman]

Hi.

Thanks for the feedback. I wasn't aware of this problem. Which front-page are you referring to?

I would like to create a separate documentation web site (could be github pages), but time does not permit that currently (it is a spare time project). But moving the documentation to a separate markdown file in the same repo would be easily doable.

[glennsl]

Great! By "front page" I just mean the README file.

Btw, part of the long term plan for redex is to automatically generate and host API reference docs. But to do so we first need a decent document generator, which might take some time to arrive, so there's certainly no reason to put your documentation web site plans on hold. But hopefulyl, some day, we'll be able to get good documentation ecosystem-wide without too much effort.

[stroiman]

I moved the docs to a separate documentation.md file (and fixed some that was out-of-date in the process :) )