[docs] Future improvements for documentation

[xiroV]

These are some comments I have written for our documentation, both developer guide and integration module documentation.

The comments have been written as I went through it in December, and since the deployed version of the documentation was not completely up to date at the time, some of these comments might already be resolved.

General Notes on UI/UX

Developer Guide

• The navigation is confusing and/or the hierarchy is too deep in my opinion.
• Data Model sections have a Properties sections under each model, which can be expanded. Often this doesn't contain anything beside what is already shown in the code. Furthermore, each element is shown as being expandable as well. These almost never contain anything either (sometimes a "Deprecated: Yes" tag). I propose that we just show everything for each element, or even better, remove expandability from both "Properties" and all elements, and present them in a more readable format.
• Bug in graphics/visual communication flow: Inner boxes expand outside outer boxes, if content is too long (example on Core/Users/Authentication/Provider Authentication).
• Bug in graphics/visual communication flow: Sometimes the image is wider than the text content, which might be necessary to display everything (?) however, it should be properly centered in that case.
• Communication Flow types: Instead of a list of expandables, I propose a horizontal list of tab-like buttons, to switch between views. That way the user doesn't have to scroll around too much either.

Integration Module Documentation

• No hover change on buttons, links or in sidebar.
• Core, Server, Products, Plugins and Recipes should probably be moved under a Configuration parent section.
• Label for "Required" parameters could be more visible (maybe a tag-like label box?)
• Missing documentation of ucloud CLI
• Download button can link to https://github.com/SDU-eScience/UCloud/releases/latest if we tag releases as "latest" on Github (I think).

Developer Guide

Accounting and Project Management

Projects

• Missing mention of the non-consuming project type (not sure if relevant).

• Missing RPC descriptions

Accounting

Visualization of Usage

• Text not emphasised correctly.

  Visualization gives the user the possibility to get an easy overview of their usage during a set period or for a given product category.

Grants

Allocation Process

• Grants.setEnabledStatus possibly renamed to GrantsEnabled.setEnabledState (?)

  Might be documented already.

• Grants.isEnabled possibly renamed to GrantsEnabled.isEnabled (?)

  Might be documented already.

Orchestration of Resources

Storage

Provider APIs

Introduction to Resources Control API

• Missing documentation and descriptions of RPCs

Drives (FileCollection)

Ingoing API

• Missing documentation and descriptions of RPCs

Outgoing API

• Missing documentation and descriptions of RPCs

Files

Ingoing API

• Missing documentation and descriptions of RPCs

Outgoing API

• Missing documentation and descriptions of RPCs

Shares

Outgoing API

• Missing documentation and descriptions of RPCs

Compute

Provider APIs

• Missing documentation and descriptions of RPC in Jobs -> Outgoing API
• Missing documentation and descriptions of RPC in Shells
• Missing documentation and descriptions of RPC in Public IPs (Network IP) -> Outgoing API
• Missing documentation and descriptions of RPC in Public Links (Ingress) -> Outgoing API
• Missing documentation and descriptions of RPC in Software Licenses -> Outgoing API

Developing UCloud

Getting Started

• Outdated. Refers to old launcher script.

Your first service

• Several things looks outdated, but some things might still be relevant/useful. Note: There's a warning in the top showing that this is outdated.

• Should be src/main/kotlin and api/src/main/kotlin I guess, since we don't currently have testing:

  You will be spending most of your time in src/jvmMain/kotlin and src/jvmTest/kotlin.

• I think we should rewrite this section completely. Creating a new service in the core probably isn't too useful knowledge, but the explanation of the structure of a service definitely is.

• Several dead links

High-Level Architecture

• Not sure if true anymore

  In development and when using integration testing, the gateway is replaced by a single JVM instance which runs all of UCloud. The launcher module and the integration-testing module implements this. These modules both use the Service instances stored in Main.kt to configure routing.

Micro Library Reference

RPC

RPC Audit

• Weird sentence

  By-default the system will audit all requests, but they use the request type.

WebSockets

• Not written

Serialization

• Weird sentence, and might be outdated:

  NOTE: This page is currently out-of-date due to a reason change to the...

Core

Core Types

API Conventions

• Several dead links
• Usage examples does not look valid anymore. I.e.

val browse = call<ResourcesBrowseRequest, PageV2<MyResource>, CommonErrorMessage>("browse") {

should be

val browse = call("browse", ResourceBrowseRequest.serializer(), PageV2.serializer(MyResource.serializer()), CommonErrorMessage.serializer()) {

API Stability

Users

User Creation

• Missing RPC descriptions

Authentication

User Authentication

• Missing RPC descriptions

Provider Authentication

• Should probably mention new launcher.

  For local development purposes only UCloud can communicate with a local provider using HTTP.

• Might be outdated, or is still a draft and needs to be rewritten: Section: Extending the Protocol to Support Verification of Client

Password Reset

SLAs

• Missing RPC descriptions

Avatars

• Missing RPC descriptions

Monitoring, Alerting and Procedures

Communication

Notifications

• Missing (some) RPC descriptions

Slack

• Missing description

Built-in Provider

• Maybe title should be changed to UCloud Provider or Integration module?

UCloud/Storage

• Documentation for Shares not written

UCloud/Compute

• Missing documentation on Plugins

---

Integration Module Documentation

Products

• Missing documentation under Examples (although this does not exist in the Core or Server sections either).

Plugins

• Extension scripts section missing content
• Description of Puhuri Project plugin parameters missing
• Description of UCloud Jobs plugin parameters missing

Recipes

Slurm + distributed file system

• Installing UCloud/IM: Link to latest release (if we tag releases as "latest")
• Basic configuration: Section under construction/incomplete
• Extensions: Section under construction/incomplete

Keycloak

• Missing documentation

Kubernetes compute with storage

• Missing documentation

Puhuri integration

• Missing documentation

[DanThrane]

I think it would also make sense to focus a bit on documentation for the frontend.