Discussion: where, and to what extent, do we document *non-napari* python things. #3750
tlambert03
started this conversation in
Ideas
Replies: 1 comment
-
Thanks for bringing this up @tlambert03, my position on other projects and the one I would also suggest for napari is that, the contribution guide should mention all this, where each topic deserves a paragraph, code pointers (how to create a virtual env, how to run linting checks etc) with links that point to in depth descriptions of each topic, that should probably point to other websites and not an in-depth section inside the napari docs. I think this is achievable and the maintenance cost is relatively low once it is in place. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
An issue that comes up very often in our documentation and our code (both when dealing with internal developers, as well as when targeting plugin developers) is "just how much" to document. In other words, how deeply should we delve, how thoroughly do we describe? What things are we responsible for teaching the reader, and what things can we expect them to know and or learn themselves with the resources already available just by googling.
I do understand the desire to be a "one-stop shop" for dipping toes into python. We often say we want napari to be a gateway drug into the world of python, and I am very much in favor of that goal. It's tempting to assume that readers may have no knowledge of X, and that we should potentially be the ones to tell them about it.
But I think we should have a discussion, and preferably have some policies in place about how much, and where, non-napari-specific information goes in. Things that I can think of that have come up in the past:
... and that's just what I could think of off the top of my head.
clearly this list is ridiculously long and complex, and takes many years to begin to understand it all. It's tempting (and admirable!) to say "maybe we can just point them in the right direction", but I do think that there is a cost, depending on where that "one more sentence" comes, and how often they are injected. That cost is essentially "tl;dr"
So, I'd love to have a rough policy or style guide about how to deal with these questions. Is a link enough? Can we say "see here for more info". Could/should we have a giant page with collapsible headings as a reference page for many of these things (so that we don't have to interject them everywhere in our documentation prose)? Is it even napari's place/job to do all this? (when I think about how I learned about all these things, it certainly wasn't from the documentation of my favorite package).
Your thoughts on the magnitude and proper placement for this type of documentation, and how it integrates into our napari-specific docs, are appreciated!
Beta Was this translation helpful? Give feedback.
All reactions