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

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 #3035
  • 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

---

Migrated from T2624 (view on Phabricator)