You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@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
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)
being much more intentional about the various entrypoints to our docs, the paths thru them, and learning ramps
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.
The scope is broad but hopefully having this issue can centralize discussions.
Ideas to improve user experience:
Ideas to improve dev experience:
The text was updated successfully, but these errors were encountered: