search

nextstrain / nextstrain.org

The Nextstrain website
https://nextstrain.org
GNU Affero General Public License v3.0
89 stars 48 forks source link

External Review of nextstrain documentation #127

Open jameshadfield opened 4 years ago

jameshadfield commented 4 years ago

This issue asks for a review of the current documentation surrounding nextstrain from those with background in this area. This review could touch on overall layout, linking between sections, and content within individual pages. Here are the main points which I see as open questions, or areas of uncertainty, from our side, and outside opinions would be valuable!

  1. We currently split docs between nextstrain.org (nextstrain.org/docs is more technical, nextstrain.org/help is intended to be more general), augur's docs (https://nextstrain-augur.readthedocs.io/en/stable/) and auspice's docs (nextstrain.github.io/auspice/). Each has different aesthetics and domains. Could this be improved?

  2. Nextstrain can be many things -- (i) a website where people view datasets generated by another party, (ii) a set of bioinformatics tools (augur) and visualisation tools (auspice), which may be run locally, (iii) a platform - nextstrain.org - to which to share their analyses. Is this communicated clearly / how could we improve clarity here?

  3. There are many ways to install the components behing nextstrain (augur, auspice, and a nextstrain-cli). How you install the tools changes the commands you need to run, and which are included in the tutorials. What is the cleanest way to present these different methods?

  4. Related to (2) - What would the best way to structure the docs to target these different use cases? E.g. tutorials for analysing your own data locally are different to a tutorial on how to interact with the visualisations at nextstrain.org/ncov

cc @colinmegill

kimdhamilton commented 4 years ago

update ~@jameshadfield @colinmegill I'll take a stab at this. Feel free to assign to me.~

starting on volunteer funneling-related process/docs instead. This issue is still poachable.

Ok if I end up breaking this into sub-issues?

colinmegill commented 4 years ago

Of course! Please do, that will help others contribute and scope conversation & ultimately lead to more bite-size PRs as well :)