Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve experience between umbrella docs project and subprojects #203

Open
victorlin opened this issue May 1, 2024 · 1 comment
Open

Comments

@victorlin
Copy link
Member

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

Ideas to improve user experience:

Ideas to improve dev experience:

@victorlin
Copy link
Member Author

From #198 (comment):

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant