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

organize documentation by wis2box roles/profiles #449

Open
tomkralidis opened this issue May 16, 2023 · 2 comments
Open

organize documentation by wis2box roles/profiles #449

tomkralidis opened this issue May 16, 2023 · 2 comments
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@tomkralidis
Copy link
Collaborator

Current wis2box documentation is split into a User Guide and Reference Guide. This can be improved further by splitting into role-based documentation.

Possible roles/profiles:

  • operator: manages / curates metadata via user interfaces
  • administrator: manages the installation, comfortable with logging into a system and working with the command line
  • other roles/profiles?

A grey area is data integration (who performs this role? Administrators?), this includes:

  • data mappings
  • hookup of data and entry point into wis2box incoming storage

Regarding implementation, it makes sense to address this issue once the metadata UIs are enabled/production ready. We should continue to gather requirements/gain clarity in the meantime.

@tomkralidis tomkralidis added documentation Improvements or additions to documentation enhancement New feature or request labels May 16, 2023
@francilly
Copy link

Here are some concrete proposals for improving the documentation of Wis2Box by segmenting it further by user roles:
For the operator:
Detailed tutorials on using the user interface for common tasks (search, download, upload, etc.)
FAQ/troubleshooting for the most common problems
Guidelines for good practices in the use and management of metadata
For the administrator:
Detailed instructions for installation, configuration, maintenance
Documentation on the architecture, components, protocols, and standards used
In-depth monitoring and troubleshooting guide
For data integrators:
Tutorials on mapping incoming data to the Wis2Box model
Guide to available data connectors and how to develop new ones
Best practices for data ingestion scripts
Monitoring of integration jobs
Transversal:
Glossary of technical terms
FAQ
Use cases by persona
References to external component documentation used
The idea is to really divide the documentation so that it corresponds closely to the specific needs of each user profile. I hope these proposals give you some ideas for structuring the future documentation of Wis2Box.

@francilly
Copy link

To complement my previous proposals, I would suggest adding the following:

A section describing the authorization model and access to data, observations, and APIs for each user role.
Clear indications on access restrictions and permissions required to access different platform components.
Instructions for administrators on user, group, and permission management.
In the sections dedicated to data operators and integrators, warnings about restricted access and a reference to the authorization model documentation.
A chapter common to all user profiles explaining the data access, observations, and API access policy, security best practices, and risks in case of misuse.
The idea is to clearly document, for each role, the permissions they have and the best practices to follow to comply with the access model. Security and access restrictions should be transparently addressed in the documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants