Page MenuHomeSoftware Heritage

Create strategy for documentation with a map or a full table of content
Open, HighPublic

Description

Since we have many entry points we should review the current map of documentation and create a uniformed strategy for what goes where and for whom.

Event Timeline

moranegg created this task.

For whoever who want to work on this (and on doc restructuring in general), I recommend to watch this talk: https://www.youtube.com/watch?v=t4vKPhjcMZg , which provides a good taxonomy of the kind of docs that exist. Our GSoD 2019 application page also contains a lot of useful related work.

@zack very good video!
Here is a short summary from the video (Daniele Procida) and from Divio's documentation website:
https://documentation.divio.com/
Four different functions:

I'm going to open a task to try this approach with the deposit documentation.

An idea for a strategy:
a "features" page on the website (which can be under About or under Archive)

Each feature/service needs:

  • a name
  • a short description
  • a link to the feature
    • on the target page should be available or linked:
      • a short/long description of the feature
      • a how to use the feature guide (as a web-app user)
      • a link to the dev docs (module) "in charge" of this feature
  • a link to the dev docs about the feature
    • on the target page should be available or linked:
      • a description of the module's scope and operations
      • a how to use/implement /contribute guide
      • a tutorial if available
      • a link to the forge's tasks/project

How to guides options:

  • how to use the feature (as a web-app user)
  • how to use/implement the feature in a workflow (with the API)
  • how to contribute to the feature

Tutorials are different from How To Guides and should be listed if available.
Tutorials are a step by step, detailed explanation to get started.
How to guides are to solve a specific problem.

Here are the tutorials I know of in SWH: