RFC: Better entry point for documentation #651
Description
I think the current Verso documentation misses opportunities to give easy entry points for new users. I've considered playing around with Verso a few times, but every time I conclude that I should come back when I have more time and energy to commit.
My biggest concern is that the templates and examples (at least the ones that are easy to find from the README) require the reader to actually install and run Verso to see how they work. Compare that to other projects with similar goals, e.g., typst, which have a simple example of the markup syntax, output, etc. as one of the first things a reader sees in the documentation. The lack of easily-accessible examples is especially problematic on mobile (where I often take the first steps of exploring new technologies), since even a motivated mobile reader can't actually run the code.
Concretely, here are some suggestions:
- Include examples of syntax and the resulting output front-and-center in the README.
- Include pre-compiled PDFs / HTML pages alongside the examples in
verso/examples. - Add a link to a hosted version of the Verso Manual as a web page, rather than as an HTML zip (important for mobile).
- Consider other ways to make both the README and the Manual a bit less theoretical. Right now they seem to target people who are passionate about documentation systems rather than people who just want to see if this tool solves their problems.
Obviously, let me know if I've missed something and these things actually exist somewhere. Google seems to be chronically bad at indexing anything and everything Lean-related, so it's possible there's a hosted version of the manual I just haven't found.
Thanks for considering this suggestion. I know that a lot of work has gone into Verso, and I'd love to see more people be able to pick it up.