search

cs3org / reva

WebDAV/gRPC/HTTP high performance server to link high level clients to storage backends
https://reva.link
Apache License 2.0
167 stars 113 forks source link

Reva documentation #3276

Open david-antos opened 2 years ago

david-antos commented 2 years ago

https://reva.link/docs/config/ is missing any explanations what the configuration options actually mean (such as "this is an address of remote server to connect to using such-and-such protocol"). Construction of toml files for deployments was based mostly on guess-work and checking source code.

Majority of toml configuration options is missing completely (or just listed without any explanation).

In general, the documentation expects more-or-less developer level knowledge of Reva functionality. There is a short overview of general concepts, there is a listing of configuration options (mostly unusable as descriptions are missing), and there also needs to be a middle layer of explanation what individual modules do, and how to combine them to a useful deployment.

I suppose that after "getting started", there is of little use to continue to "tutorials" as suggested, and I got completely lost in concepts section (as writing plugins is hardly among the first things one needs to know and the "storage drivers" part is missing basic explanation what the module is actually made for, so I fail to understand it completely).

I'd suggest that the reference manual of configuration options is of higher priority at this point.

david-antos commented 1 year ago

I'm afraid this is quite crucial part of ScienceMesh deployments and the documentation is clearly mostly missing. Any plans to handle that?

labkode commented 1 year ago

@david-antos what areas should we look in priority? @gmgigi96 can you please follow-up on this while I'm away?

david-antos commented 1 year ago

Well, it's tempting to say "all of it", but let's be realistic and prioritise. It would be great to decide what belongs where. We discussed with @michielbdejong and came out with a principle that installation of Reva and configuration of it to work with OC10 and NC should be a part of Reva documentation as they are generic. The "Science Mesh docs" should just describe configs specific for Science Mesh deployments. I'd also suggest that we have commented example configuration files (again, if they are Mesh specific, may be on https://developer.sciencemesh.io/docs/, otherwise in Reva docs), but ALL of options that are expected to be tuned by anybody deploying Reva for the Mesh need to be described in Reva reference manual (not just listed, described, so that people can really configure them without the need to study source code). Michiel indicated last week he'll create a pull request to Reva documentation, so I'd definitely suggest fine-tuning the division of the documentation between "Mesh specific" and "Reva general" with him.

mirekys commented 1 year ago

Michiel has put a list of missing module docs that are referenced from https://developer.sciencemesh.io/docs/ here: https://github.com/cs3org/reva/issues/3532, all of which are commonly used by all IOP deployments