Reorganising and improving plugin documentation #153
Comments
seankmartin
changed the title
|
One thing that would be nice to add into the publishing step is some information about the npe2api and how this relates to and forms the backbone of the napari plugin installer menu. For instance, that the installer menu is populated from the summary information for each plugin. This could also be a good place to bring up bundled napari support - since I think (and please correct me if I have this wrong, I'm not 100% versed on the npe2api) that a napari plugin only supports bundled napari if it exists at https://npe2api.vercel.app/api/conda/{plugin-name} and the conda_platforms information matches your OS. Also, it would seem to me that all of the plugins in npe2api errors.json can't be used in the napari viewer due to manifest (or other) errors? If that is correct - then we could point out to check this page to make sure your plugin is not there! |
|
This looks outstanding! Wow! Thanks for putting the time into this. One tiny note, but in that mockup I think it may worth emphasizing and splitting the paths for the two personas even more. I doubt there is any overlap between them in terms of content expectations. Maybe arrange the two persona tiles side by side? or using tabs like some of the other docs where we have pip and conda or something? |
Possible PRs to restructure and add content to the plugin documentationThis is a possible set of PRs that might be required to achieve Proposed pull requestsOrganize content
Plugin fundamentals
Update content
New guides
New tutorials
Hub related information
Concerns
A visual representation of the pull requestsClick to view the diagram
|
|
One thing that came to mind is explaining/contrasting plugins vs. widgets. |
|
Tracking related PRs:
|
# Description I've reorganised the content of /plugins following #153. I'm interested to see what you think! I was very heavy handed with the use of grids for the index pages, because they are the best I could think of. Open to other options as always. I also fixed a small number links on other pages outside of /plugins because I broke a lot of links with this restructure and I wasn't exactly sure what I caused and what was already broken - thought it was safer to just fix them. Here is what the homepage of plugins would look like:  ## Type of change - [x] Fixes or improves existing content - [x] Adds new content page(s) ## Final checklist: - [x] My PR is the minimum possible work for the desired functionality ## Addendum A small number of my commits got associated with my bot account (I set the wrong email in my git config because I deleted my config before creating #201 🙈). I genuinely don't know how to fix that. If it is going to be an issue I could make a new branch and squash all the commits into one big commit from my seankmartin account.
# Description I've reorganised the content of /plugins following napari#153. I'm interested to see what you think! I was very heavy handed with the use of grids for the index pages, because they are the best I could think of. Open to other options as always. I also fixed a small number links on other pages outside of /plugins because I broke a lot of links with this restructure and I wasn't exactly sure what I caused and what was already broken - thought it was safer to just fix them. Here is what the homepage of plugins would look like:  ## Type of change - [x] Fixes or improves existing content - [x] Adds new content page(s) ## Final checklist: - [x] My PR is the minimum possible work for the desired functionality ## Addendum A small number of my commits got associated with my bot account (I set the wrong email in my git config because I deleted my config before creating napari#201 🙈). I genuinely don't know how to fix that. If it is going to be an issue I could make a new branch and squash all the commits into one big commit from my seankmartin account.
|
#239 could fall under this body of work. |
Uh oh!
There was an error while loading. Please reload this page.
📚 New content request
Hello everyone!
The napari plugin ecosystem and the content at napari.org/plugins have been growing rapidly, and it would be beneficial to reorganize the plugin documentation to improve navigation. Here is a proposal for restructuring the existing plugin-related content and introducing new valuable information. This layout has already been shared with @DragaDoncila and the initial round of feedback has been incorporated into this proposal. Please add any suggestions or comments regarding this proposal - I'd love to hear your thoughts!
Mock-up of the plugins main page
Here is a mock-up of the proposed site layout at a top level:
Proposed plugin documentation structure
Click to view the full plugin site layout proposal
Click to view the proposed table of contents
How this proposal was developed
The proposed reorganisation and new pages have tried to follow the ideas from the Diátaxis framework, splitting documentation into Tutorials (step by step lessons or learning experiences), How-to guides (directions to solve specific problems), Explanations (understanding oriented discussions), and Reference (information-oriented technical descriptions) pages. The layout draws inspiration from the documentation of other open source projects with plugin or extension capabilities, napari plugin related content in external sites, and the recent updates to the napari.org site to use grid layouts on index pages.
This layout aims to achieve two main objectives:
Aim 1: align documentation with user/developer flow
Click to view personas and flow diagrams
The goal is to divide the documentation into pages that cater to either users or developers. We assume that plugin users want to discover, install, and effectively utilise plugins to solve their problems. On the other hand, plugin developers want to build and maintain plugins to support the users. The documentation should align with the typical flow for both users and developers, considering that these groups are not mutually exclusive. Additionally, this division between users and developers can also help describe when a user might consider becoming a plugin developer, how to do so, and what makes a great plugin. For example, this information would be useful if a user wants to share their napari script or widget with others or contribute to an existing plugin.
Aim 2: centralise plugin information
Currently, there is a wealth of information for plugin users and developers, but it is somewhat scattered. The goal is to centralise this information on the plugins site. Importantly, the aim is not to duplicate content on napari.org but to provide short summaries and cross-link to the relevant main information page. At the end of this issue, you'll find a non-exhaustive table which lists many of the current resources that are available for plugin developers and users.
The location of napari hub related documentation
The proposal includes incorporating some napari hub related documentation on the napari site.
This is in an effort to encapsulate information in one highly discoverable documentation area, benefiting both the typical user journey, which often involves finding plugins on the napari hub, and the typical developer journey, which usually ends with publishing their package to PyPI and the napari hub. By placing napari hub related information on the napari site, it may make it clearer how to use the built in napari functionality (such as the plugin installer menu) in conjunction with or separately from the napari hub. Additionally, it may help clarify the usage of plugin metadata by napari itself, its usage by the napari hub, and the overlap between them.
However, very good cases can also be made for keeping napari.org/plugins completely separate from hub related information. In this case, perhaps that information could be placed on the napari hub and cross linked to from this documentation.
Implementation
The implementation of this proposal would involve:
This process would likely occur in stages. The reorganisation of the existing documentation would be prioritised, allowing it to be available in the new structure as soon as possible. The consolidation of existing information would follow, and new pages would be created as time permits.
Related issues
There is one main open issue with some overall suggestions on how to structure and add to the plugin developer information (as opposed to a specific page change, for e.g.), which could be integrated as part of this effort #25.
However, there are also many open issues related to specific changes to certain pages. These issues are not listed here to maintain focused on the overall structural improvements.
Resources for documentation
Here is a non-exhaustive list of resources that are currently available for plugin developers and users. These resources could all be valuable in the creation of the new plugin documentation.
Click to view the plugin documentation resources
The text was updated successfully, but these errors were encountered: