search

threatgrid / asami

A graph store for Clojure and ClojureScript
Eclipse Public License 1.0
634 stars 29 forks source link

Refactor the README #203

Open quoll opened 3 years ago

quoll commented 3 years ago

A project README should contain enough to introduce a user to a project, provide a sense of the functionality, and show them how to get started using it.

For small projects, a README can serve the purpose of providing all of the documentation. Asami developed past this a long time ago, moving the documentation into the wiki. However, a lot of excessive documentation and samples are still on the front page.

We need to refactor the front page to provide introductory information, but not be so intimidating for new users. The current information is possibly fine as it is, but instead of filling up the opening page, maybe it could be moved into a tutorial page or something similar. Also, various features should use links to the appropriate parts of the wiki to provide a full explanation.

noprompt commented 3 years ago

What do you think about using the doc/ directory and leveraging cljdoc? From personal experience, this has worked out fairly well for Meander and I think it could work well for this project. Here is the cljdoc for the latest release of the library. The README, additional articles, and namespace documentation are all included.

noprompt commented 3 years ago

For convenience, here you can find Meanders doc/ directory and the cljdoc configuration.