organize documentation by wis2box roles/profiles

[tomkralidis]

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.

[francilly]

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]

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.