search

kanaverse / kana

Single cell analysis in the browser
https://kanaverse.org/kana/
MIT License
142 stars 12 forks source link

[JOSS] Web app usage guidance #238

Closed yongrenjie closed 1 year ago

yongrenjie commented 1 year ago

(This issue is opened as part of @yongrenjie and @llewelld's review of the Journal of Open Source Software submission, 'Powering single-cell analyses in the browser with WebAssembly'.)

Documentation is fairly sparse, in that there's a README.md, but no other documentation in the repo. However, the README.md does give a high-level overview with relevant content and points the user to a book, written by the authors (and others), which follows the same flow (although this uses the R version of scran).

When running, the app is well supported with instruction pages, tooltips and help buttons. However there isn't any detailed in-app reference documentation. The app is generally quite intuitive, so this isn't necessarily a problem, but a link to some more detailed documentation, or a tutorial document to walk the user through an example, would be helpful either in the README.md or as part of the app itself (there may already be something that we missed).

jkanche commented 1 year ago

We've started to incorporate how-to tutorials in the Wiki. We'll try to keep this updated as we add more features.

llewelld commented 1 year ago

The wiki is a nice start. This kind of documentation would be a great place to start fostering a community as it's a low-bar entry point for new contributors. Currently there doesn't seem to be an easy way for non-project-members to contribute to the wiki.

The reason I noticed is because I was hoping to create a PR to update a link in Home.md, which seems to be misdirected (or maybe missing?) right now.

How to use the explore mode
From: https://github.com/kanaverse/kana/wiki/How-to-Explore-mode
To: https://github.com/kanaverse/kana/wiki/How-to-explore-pre%E2%80%90analyzed-single%E2%80%90cell-datasets

yongrenjie commented 1 year ago

Looks good! The only thing I'd suggest is to add a link to this wiki to the kana web app itself, so that it's more discoverable. (Unless there's already one and I missed it?)

jkanche commented 1 year ago

I've fixed the link to explore datasets and also added the link to the wiki in the README.