Restructuring the Scicat documentation

[LAShemilt]

The migration for loopback to nest js has seen a lot of changes between Scicat V3 and Scicat v4. The current documentation structure is hard to navigate. I propose that we restructure it into the following for ease of finding information:

• Quick Start guide
  • a guide to getting started with SciCat, using local installation, docker and minikube
• Introduction to the SciCat Metadata Catalogue
  • describing the functionality of SciCat and the aims of the project
• Data Model
  • a description of the data model used in Scicat
• Ingesting Data
  • a guide on how to ingest metadata into your SciCat deployment
• Configuring SciCat for your Project
  • Introducing the Backend and Frontend Configs
    • a description of what can be configured here
    • how to serve these configs so they can be read by SciCat.
  • Authentication
    • Set up with functional Accounts
    • OIDC setup
    • LDAP Setup
  • Using the Jobs Mechanism
  • Publishing Datasets
• Using Additional Features
  • adding elastic search
• Developing SciCat
  • description of the software structure
  • how to get involved with the community

I would be interested to hear thoughts on this new structure and how it might be extended.

[sbliven]

Where would the user guides be?

[LAShemilt]

That is a good question. I would probably add a separate section for a User Guide. Some of these would be site specific, but we can offer a general one here, relating to scicatlive, which would just have the basics

[LAShemilt]

Further discussion and work on this issue, has resulted in a different proposed structure.

Splitting the documentation up into two repos for two audiences - one is user-documentation which has the user facing guidelines. This repository would remain for the operator and developer documentation.

Here I think the structure could be the following:

• Quick Start guide
  • a guide to getting started with SciCat, pointing to the installation with Scicat Live
• Data Model
  a description of the data model used in Scicat
• Ingesting Data
  a guide on how to ingest metadata into your SciCat deployment
• Authentication
  - Set up with functional Accounts
  - OIDC setup
  - LDAP Setup
• Configuring SciCat for your Project
  • Backend
    • v3.x
    • v4.x
  • Frontend
  • Jobs
  • Publishing Datasets
  • Elastic Search
• Development Guide
  • Contributing
  • Backend
    • v3.x
    • v4.x
    • Overview
    • Swagger UI
    • Metadata Description
  • Frontend
    • Overview
  • Testing