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](https://hedgedoc.softwareheritage.org/XzWzD-WoQOSD?both)
[presentation of strategy](https://hedgedoc.softwareheritage.org/EZR2580uS_60pBRft9-sUQ?both)
## 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](https://www.softwareheritage.org/wp-content/uploads/2021/02/swh-dataflow-merkle.png)
## 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