Page MenuHomeSoftware Heritage

Create strategy for documentation with a map or a full table of content
Started, Work in Progress, 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.

What do we have?

https://forge.softwareheritage.org/file/data/fvlipulkzggvyhc42ivu/PHID-FILE-wjjjf5zxr5bukuf34lhr/SWH-world.png

What are we missing?

  • clear strategy what goes where
  • links from one location to another
  • permanent homes for important/useful information

Proposed solutions

The March documentation mini-sprint
presentation of strategy

Docs - main page docs.swh.org

  • docs.swh.org/devel
  • docs.swh.org/user (can be use/usage/services)
  • docs.swh.org/sysadm
  • docs.swh.org/FAQ (divided in the page by themes and personas)
Docs for contributors

in relatively good shape: https://docs.softwareheritage.org/devel/

Docs for users -> To be created

Usage as a service (not the tools)

  • Getting started (tutorials)
    • searching an origin
    • browsing code
  • Guides (How to)
    • get and choose a swhid
    • list visits
    • save code now
      • with the web platform
      • with the API
    • search metadata
    • deposit software source code on partner platform
      • HAL
      • IPOL
  • Explanation => FAQ for visitors on website?
    • why SWH?
    • architecture
    • pull vs push
    • delay/lag
    • ...
Docs for sys-admins (for deployment) -> To be created
  • Getting started
    • clone repo and puppet
    • vagrant
    • credentials
    • link to the phabricator tuto in devel doc
  • Guides (How to)
    • Debian packaging
    • Database deployment
    • Deploying a lister
    • Keycloak?
  • Explanation
    • Infrastructure
    • Staging

READMEs

  • symlink vers docs/README.rst
  • docs/README.rst included in docs/index.rst, like:
 .. _swh-fuse:

.. include:: README.rst


.. toctree::
   :maxdepth: 1
   :caption: Overview

   cli
   configuration
   Design notes <design>
   Tutorial <tutorial>
   API reference </apidoc/swh.fuse>
Post-migration

Install a redirect link in the migrated page from the wiki, for example:

#REDIRECT [[swhdocs:devel/contributing/git-style-guide.html]]

FAQ

  • FAQ for visitors-> to be created on website (on www.softwareheritage.org/FAQ/)
  • FAQ page on docs.softwareheritage.org/FAQ/ should be more technical - to answer contributors questions
  • add link from main docs page to FAQ
  • links from each section (devel, sysadm, user) to dedicated parts in FAQ or visitor's FAQ on website
  • add link to docs FAQ page from website FAQ

Wiki

  • Keep internship and bibliography pages in wiki
  • Do not delete pages - add link to new location and add deprecated announcement on wiki page
  • Triage pages in wiki T3035
    • Review full content (bibliography)
  • Move devel/sys-admin pages to docs (sensible info should stay private on intranet or in a private section in docs)
  • Main page
    • Update to better reflect the information in wiki
    • Add links to specific sections in docs and on website
    • Add links to website, archive and docs
  • Hide WG pages from main page (will be added when group is activated)
  • Restructure navigation

Archive

  • add links
    • from docs.swh.org/devel to Web API
    • from Web API to docs.swh.org/devel
    • from docs.swh.org/devel directly to endpoints
  • have more visible access to endpoints on Web API page
  • what to do with archive help page: https://archive.softwareheritage.org/browse/help/
    • redirect to docs.swh.org/user/ when it is created

Website

  • add services page to link to features, docs and guides
  • review blog post case by case and find permanent home for information
  • simplify diagrams from presentations: swh-dataflow-merkle

Next pragmatic steps

Step 1: Be exhaustive and clear on tasks
Step 2: Provide structures and links between locations
Step 3: Improve current diff requirements to include documentation of change
Step 4: Re-organize existing information
Step 5: Write missing guides and information

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.

This comment was removed by moranegg.
This comment was removed by moranegg.
This comment was removed by moranegg.
moranegg changed the task status from Open to Work in Progress.Feb 10 2021, 4:34 PM