Page MenuHomeSoftware Heritage

Restructure deposit documentation with a clearer strategy
Closed, ResolvedPublic

Description

First verify if the deposit documentation can be structured with Divio's ideas:
https://documentation.divio.com/introduction/

As presented by Daniele Procida on:
https://www.youtube.com/watch?v=t4vKPhjcMZg


The current deposit table of contents is the following:
swh.deposit (Description subsection and Contents subsection)
In the Description the following items are hilghligthed:

In the Description, the list of direct links:

  • User Manual page
  • API Documentation reference pages
  • Hacking on swh-deposit
  • Deployment of the swh-deposit

In the Contents, here is the full TOC:

Reference Documentation

Event Timeline

moranegg created this task.

Please free to complete or comment specific parts of this overview:

From a personas point of view, we have:
user: people who want to use the deposit feature (e.g deposit clients)
visitors: people who want to checkout the deposit to see what is it about, for example to check if it is FAIR or if it can be used for their service
contributors: people who want to contribute to the SWH project, specifically on the deposit feature

Users

Who are the deposit users? what do they use?

  1. HAL (SWORD server)
  2. IPOL (swh-deposit cli)
  3. Intel? (swh-deposit cli)
  4. InvenioRDM development team (?) =>
    • potential clients from each InvenioRDM instance
    • could be Zenodo

What information is needed and in what form (tutorial, how to, reference, discussion) for a user?

  • how to start depositing from scratch? (without creds)
  • how to deposit different kinds of deposits (content + metadata, only-metadata) with the swh-deposit cli?
  • how to deposit different kinds of deposits (content + metadata, only-metadata) directly to the SWORD server?
  • What are the requirements for a deposit?
  • What is the result of the deposit?

Visitors

Who are potential visitors?

  • SWH sponsors
  • SWH ambassadors
  • SWH prospects clients
  • rest of the world :-)

What information is needed and in what form (tutorial, how to, reference, discussion) for a visitor?

Contributors

Who are the deposit contributors?

  1. SWH team (@ardumont, @vlorentz, @douardda, etc.)
    • at the moment there are no internship available on the subject
    • at the moment there are no external contributions

What information is needed and in what form (tutorial, how to, reference, discussion) for a contributor?

  • Where and how the swh-deposit is developed? (link to repository and task board)
  • Who to contact if you want to contribute?
  • Where to start locally? What to install?
  • How to test your work?
  • Frequent questions / errors?
moranegg changed the task status from Open to Work in Progress.Jan 26 2021, 11:34 AM
moranegg moved this task from Backlog to In progress on the SWORD deposit board.
moranegg reassigned this task from moranegg to vlorentz.

@vlorentz has added high level menu:

  • Deposit API
  • Deposit internals
  • Specifications