search

nextstrain / docs.nextstrain.org

Umbrella documentation project for Nextstrain
https://docs.nextstrain.org
17 stars 13 forks source link

Improve experience between umbrella docs project and subprojects #203

Open victorlin opened 2 weeks ago

victorlin commented 2 weeks ago

The scope is broad but hopefully having this issue can centralize discussions.

Ideas to improve user experience:

Ideas to improve dev experience:

victorlin commented 2 weeks ago

From https://github.com/nextstrain/docs.nextstrain.org/pull/198#discussion_r1581437145:

@jameshadfield: From a technical standpoint the fetching of docs has a whole bunch of papercuts and I'd be very happy to see us move past this. However for my money it is a symptom of our siloed docs setup, and there are larger organizational / design issues.

The whole setup of the docs is changeable from my point of view. This is all to say that if you would like to make bigger changes then I'd encourage this.

@tsibley: I agree with @jameshadfield that there's still a good bit of holistic work to be done to improve our doc organization. I'm not sure if we agree on what that work is though! 🙃 James, would you say more (here, or elsewhere) on "our siloed docs setup" and what "larger organizational / design issues" there are to fix in your eyes?

In my eyes, briefly and off-hand, the work is around

  1. more cleanly separating reference material (versioned in step with the software; co-located with source code) from other higher-level or cross-cutting material (usually not versioned; not necessarily co-located)
  2. being much more intentional about the various entrypoints to our docs, the paths thru them, and learning ramps
  3. improving navigation and wayfinding as our docs naturally sprawl across high vs. low-level concerns, single software components vs. whole systems, reference material vs. introductory tutorials.