Documentation rework

Following the diataxis principles the documentation could be reorganized in 4 parts plus the homepage:

0. homepage: simple page to guide first comers (You are... You want ... then ...)
1. explanation: what's a deposit ? is it useful to me ?
2. howto: guide knowledgeable users through the deposit process
3. references: technical docs (API, CLI, workflow)
4. tutorial: hands-on documentation

detailed outline

1. Explanations
   1. What's a deposit?
   2. Why do we need metadata?
   3. What's a code deposit?
   4. What's a metadata only deposit?
2. Howto...
   1. Request an account
   2. Prepare your metadata and artifacts
      1. metadata with archives
      2. metadata only
   3. Make a code deposit
      1. requisites (account, prepared artifacts, CLI or API)
      2. make the deposit
         1. one shot
         2. partial
      3. check its status
   4. Make a metadata deposit
      1. requisites (account, prepared artifacts, CLI or API)
      2. make the deposit
      3. check its status
   5. Deposit a new version of an existing origin
      1. requisites (account, prepared artifacts, CLI or API, deposit a previous version)
      2. make the deposit
      3. check its status
   6. Integrate a deposit to your website
      1. swhid / qualified swhid
      2. iframe
   7. Contribute to the deposit service
      1. work groups
      2. code
3. References
   1. Internal Workflow
   2. Real-world examples / integrations
   3. Metadata
      1. Intrinsic metadata
      2. Extrinsic metadata
   4. Deposit API
   5. Deposit CLI
   6. swh-deposit package documentation
4. Tutorials
   1. make a deposit to the staging env using the CLI
   2. make a deposit to the staging env using the API

added activity::Documentation label

assigned to @rboyer

@moranegg here's my proposal for a redesign of the deposit documentation

Thank you @rboyer! I really like this overall structure. Only comment is on the usage of the word "data" -> we should refrain on doing so because we try to distinguish source code artifects and data in the Open Science context.

In prepare your metadata and artfacts (instead of data), I would suggest the following:

• metadata with archives
• metadata only
• why do we need metadata: reference to extrinsic metadata spec: https://docs.softwareheritage.org/devel/swh-storage/extrinsic-metadata-specification.html

Have you seen the related issues on this topic:

• #4650
• #4651
• #4652

changed the description

changed the description

First of all:

Have you seen the related issues on this topic: [...]

No, I hadn't seen those tickets, I jumped in without looking beforehand

Only comment is on the usage of the word "data" -> we should refrain on doing so because we try to distinguish source code artifects and data in the Open Science context.

Noted, thank you for the clarification.

In prepare your metadata and artfacts (instead of data), I would suggest the following: [...]

Thanks, I've added metadata with archives & metadata only to Howto prepare your metadata and artifacts.

Correct me if I'm wrong but Why do we need metadata? feels more like an Explanation to me so I've added it there and I've divided the Metadata reference in two : Intrinsic & Extrinsic.

Let me know if you're ok with this, and thanks again for your feedback!

@moranegg I found a Review existing documentation according to identified personas in the roadmap:

The existing documentation is fairly extensive but somewhat unfocused. There is work scheduled to come up with personas to reflect on various Software Heritage stakeholders. Once that work is done, the existing documentation should be reviewed to identify who could be interested in which parts.

Are the identified personas here (visitors, users, contributors) or is there more fine grained / specific personas related to Deposit somewhere ?

Yes we do have :)

Here is the one related to deposit: https://hedgedoc.softwareheritage.org/personas-workshop-profile-P1

This was during our personas workshop in April: https://hedgedoc.softwareheritage.org/E6nAPDiYR92NF82NK_QE7w

And the permanent home for personas is now here (but still WIP): https://gitlab.softwareheritage.org/outreach/community/personas

We never got the "green light" to show this to the team..

@bchauvet @douardda

I also found this: https://hedgedoc.softwareheritage.org/FAIRCORE4EOSC-metadata-template

mentioned in merge request swh-docs!475 (merged)

@moranegg do you have at hand some content for the "How to contribute to the deposit service" from the participate to our workgroups (it's fun) perspective ?

changed the description

@rboyer I think I might have text in emails, but not "real documentation".

Also, "how to contribute" is ambiguous, we don't expect deposit partners to contribute code.. so maybe "how to participate" or "how to engage with.."

There is the Deposit Interest group Membership for monetary contributions. I'll check if I can find something structured for you.