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?
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